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

@@ -45,10 +45,16 @@ class DataverseClient:
     .. note::
         The client lazily initializes its internal OData client on first use, allowing lightweight construction without immediate network calls.
 
+    .. note::
+        All methods that communicate with the Dataverse Web API may raise
+        :class:`~PowerPlatform.Dataverse.core.errors.HttpError` on non-successful
+        HTTP responses (e.g. 401, 403, 404, 429, 500). Individual method
+        docstrings document only domain-specific exceptions.
+
     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 +283,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

@@ -140,10 +140,8 @@ 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.HttpError:
-            If the Web API returns an error.
+        :raises ~PowerPlatform.Dataverse.core.errors.ValidationError:
+            If ``sql`` is not a string or is empty.
 
         Example:
             Basic SQL query::

src/PowerPlatform/Dataverse/operations/records.py

@@ -88,13 +88,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
 

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.