Fix PR review comments: docstrings, error docs, and create() validation

- Document type aliases in tables.create() columns param (#4)
- Clarify SQL description in client namespace summary (#8)
- Add :raises: for HttpError, ValidationError, ValueError across all
  operation methods (#6)
- Fix query.sql() to document ValidationError instead of incorrect
  SQLParseError
- Restore post-call validation in records.create() matching original
  client.create() behavior (#9)
- Improve deprecated get() docstring with explicit guidance on when to
  use records.get() vs query.get() (#10)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tpellissier

src/PowerPlatform/Dataverse/client.py

@@ -48,7 +48,7 @@ class DataverseClient:
     Operations are organized into namespaces:
 
     - ``client.records`` -- create, update, delete, get individual records
-    - ``client.query`` -- paginated queries and SQL
+    - ``client.query`` -- paginated OData queries and read-only SQL queries (via Web API ``?sql=`` parameter)
     - ``client.tables`` -- table and column metadata management
 
     Example:
@@ -277,8 +277,10 @@ def get(
     ) -> Union[Dict[str, Any], Iterable[List[Dict[str, Any]]]]:
         """
         .. note::
-            Deprecated. Use :meth:`~PowerPlatform.Dataverse.operations.records.RecordOperations.get`
-            or :meth:`~PowerPlatform.Dataverse.operations.query.QueryOperations.get` instead.
+            Deprecated. This method has been split into two:
+
+            - **Single record by ID** -- use ``client.records.get(table, record_id)``
+            - **Query / filter multiple records** -- use ``client.query.get(table, filter=..., select=...)``
 
         Fetch a single record by ID or query multiple records.
 

src/PowerPlatform/Dataverse/operations/query.py

@@ -88,6 +88,9 @@ def get(
             dictionaries.
         :rtype: Iterable[list[dict[str, Any]]]
 
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
+
         Example:
             Query with filtering and pagination::
 
@@ -140,10 +143,10 @@ def sql(self, sql: str) -> List[Dict[str, Any]]:
             rows match.
         :rtype: list[dict[str, Any]]
 
-        :raises ~PowerPlatform.Dataverse.core.errors.SQLParseError:
-            If the SQL query uses unsupported syntax.
+        :raises ~PowerPlatform.Dataverse.core.errors.ValidationError:
+            If ``sql`` is not a string or is empty.
         :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
-            If the Web API returns an error.
+            If the Dataverse Web API returns an error.
 
         Example:
             Basic SQL query::

src/PowerPlatform/Dataverse/operations/records.py

@@ -73,6 +73,8 @@ def create(
         :rtype: str | list[str]
 
         :raises TypeError: If ``data`` is not a dict or list[dict].
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
 
         Example:
             Create a single record::
@@ -88,13 +90,19 @@ def create(
                 ])
                 print(f"Created {len(guids)} accounts")
         """
-        if not isinstance(data, (dict, list)):
-            raise TypeError("data must be dict or list[dict]")
         with self._client._scoped_odata() as od:
             entity_set = od._entity_set_from_schema_name(table)
             if isinstance(data, dict):
-                return od._create(entity_set, table, data)
-            return od._create_multiple(entity_set, table, data)
+                rid = od._create(entity_set, table, data)
+                if not isinstance(rid, str):
+                    raise TypeError("_create (single) did not return GUID string")
+                return rid
+            if isinstance(data, list):
+                ids = od._create_multiple(entity_set, table, data)
+                if not isinstance(ids, list) or not all(isinstance(x, str) for x in ids):
+                    raise TypeError("_create (multi) did not return list[str]")
+                return ids
+        raise TypeError("data must be dict or list[dict]")
 
     # ------------------------------------------------------------------ update
 
@@ -125,6 +133,8 @@ def update(
 
         :raises TypeError: If ``ids`` is not str or list[str], or if ``changes``
             does not match the expected pattern.
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
 
         Example:
             Single update::
@@ -188,6 +198,8 @@ def delete(
         :rtype: str | None
 
         :raises TypeError: If ``ids`` is not str or list[str].
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
 
         Example:
             Delete a single record::
@@ -237,6 +249,8 @@ def get(
         :rtype: dict[str, Any]
 
         :raises TypeError: If ``record_id`` is not a string.
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
 
         Example:
             Fetch a record with selected columns::

src/PowerPlatform/Dataverse/operations/tables.py

@@ -69,9 +69,12 @@ def create(
             (e.g. ``"new_MyTestTable"``).
         :type table: str
         :param columns: Mapping of column schema names (with customization
-            prefix) to their types. Supported types include ``"string"``,
-            ``"int"``, ``"decimal"``, ``"float"``, ``"datetime"``, ``"bool"``,
-            ``"file"``, and ``Enum`` subclasses (for local option sets).
+            prefix) to their types. Supported types include ``"string"``
+            (or ``"text"``), ``"int"`` (or ``"integer"``), ``"decimal"``
+            (or ``"money"``), ``"float"`` (or ``"double"``), ``"datetime"``
+            (or ``"date"``), ``"bool"`` (or ``"boolean"``), ``"file"``, and
+            ``Enum`` subclasses
+            (for local option sets).
         :type columns: dict[str, Any]
         :param solution: Optional solution unique name that should own the new
             table. When omitted the table is created in the default solution.
@@ -88,6 +91,9 @@ def create(
 
         :raises ~PowerPlatform.Dataverse.core.errors.MetadataError:
             If table creation fails or the table already exists.
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
+        :raises ValueError: If a column type string is not recognized.
 
         Example:
             Create a table with simple columns::
@@ -128,6 +134,8 @@ def delete(self, table: str) -> None:
 
         :raises ~PowerPlatform.Dataverse.core.errors.MetadataError:
             If the table does not exist or deletion fails.
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
 
         .. warning::
             This operation is irreversible and will delete all records in the
@@ -154,6 +162,9 @@ def get(self, table: str) -> Optional[Dict[str, Any]]:
             Returns None if the table is not found.
         :rtype: dict[str, Any] | None
 
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
+
         Example::
 
             info = client.tables.get("new_MyTestTable")
@@ -172,6 +183,9 @@ def list(self) -> List[Dict[str, Any]]:
         :return: List of EntityDefinition metadata dictionaries.
         :rtype: list[dict[str, Any]]
 
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
+
         Example::
 
             tables = client.tables.list()
@@ -202,6 +216,9 @@ def add_columns(
 
         :raises ~PowerPlatform.Dataverse.core.errors.MetadataError:
             If the table does not exist.
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
+        :raises ValueError: If a column type string is not recognized.
 
         Example::
 
@@ -235,6 +252,8 @@ def remove_columns(
 
         :raises ~PowerPlatform.Dataverse.core.errors.MetadataError:
             If the table or a specified column does not exist.
+        :raises ~PowerPlatform.Dataverse.core.errors.HttpError:
+            If the Dataverse Web API returns an error.
 
         Example::