Add operation namespaces (client.records, client.query, client.tables)

Reorganize SDK public API into three operation namespaces per the SDK
Redesign Summary. New namespace methods use cleaner signatures (keyword-only
params, @overload for single/bulk, renamed table params) while all existing
flat methods (client.create, client.get, etc.) continue to work unchanged
with deprecation warnings that point to the new equivalents.

Key changes:
- records.create() returns str for single, list[str] for bulk
- query.get() handles paginated multi-record queries
- tables.create() uses solution= and primary_column= keyword args
- 40 new unit tests (75 total, all passing)

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

Author: tpellissier

src/PowerPlatform/Dataverse/__init__.py

@@ -2,5 +2,15 @@
 # Licensed under the MIT license.
 
 from .__version__ import __version__
+from .client import DataverseClient
+from .operations.records import RecordOperations
+from .operations.query import QueryOperations
+from .operations.tables import TableOperations
 
-__all__ = ["__version__"]
+__all__ = [
+    "__version__",
+    "DataverseClient",
+    "RecordOperations",
+    "QueryOperations",
+    "TableOperations",
+]

src/PowerPlatform/Dataverse/client.py

@@ -6,11 +6,16 @@
 from typing import Any, Dict, Optional, Union, List, Iterable, Iterator
 from contextlib import contextmanager
 
+import warnings
+
 from azure.core.credentials import TokenCredential
 
 from .core._auth import _AuthManager
 from .core.config import DataverseConfig
 from .data._odata import _ODataClient
+from .operations.records import RecordOperations
+from .operations.query import QueryOperations
+from .operations.tables import TableOperations
 
 
 class DataverseClient:
@@ -82,6 +87,11 @@ def __init__(
         self._config = config or DataverseConfig.from_env()
         self._odata: Optional[_ODataClient] = None
 
+        # Operation namespaces
+        self.records = RecordOperations(self)
+        self.query = QueryOperations(self)
+        self.tables = TableOperations(self)
+
     def _get_odata(self) -> _ODataClient:
         """
         Get or create the internal OData client instance.
@@ -110,6 +120,9 @@ def _scoped_odata(self) -> Iterator[_ODataClient]:
     # ---------------- Unified CRUD: create/update/delete ----------------
     def create(self, table_schema_name: str, records: Union[Dict[str, Any], List[Dict[str, Any]]]) -> List[str]:
         """
+        .. deprecated::
+            Use :meth:`client.records.create()` instead.
+
         Create one or more records by table name.
 
         :param table_schema_name: Schema name of the table (e.g. ``"account"``, ``"contact"``, or ``"new_MyTestTable"``).
@@ -140,25 +153,23 @@ def create(self, table_schema_name: str, records: Union[Dict[str, Any], List[Dic
                 ids = client.create("account", records)
                 print(f"Created {len(ids)} accounts")
         """
-        with self._scoped_odata() as od:
-            entity_set = od._entity_set_from_schema_name(table_schema_name)
-            if isinstance(records, dict):
-                rid = od._create(entity_set, table_schema_name, records)
-                # _create returns str on single input
-                if not isinstance(rid, str):
-                    raise TypeError("_create (single) did not return GUID string")
-                return [rid]
-            if isinstance(records, list):
-                ids = od._create_multiple(entity_set, table_schema_name, records)
-                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("records must be dict or list[dict]")
+        warnings.warn(
+            "client.create() is deprecated. Use client.records.create() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        result = self.records.create(table_schema_name, records)
+        # Old API always returned list[str], new returns str for single
+        if isinstance(records, dict):
+            return [result]
+        return result
 
     def update(
         self, table_schema_name: str, ids: Union[str, List[str]], changes: Union[Dict[str, Any], List[Dict[str, Any]]]
     ) -> None:
         """
+        .. deprecated::
+            Use :meth:`client.records.update()` instead.
+
         Update one or more records.
 
         This method supports three usage patterns:
@@ -200,16 +211,11 @@ def update(
                 ]
                 client.update("account", ids, changes)
         """
-        with self._scoped_odata() as od:
-            if isinstance(ids, str):
-                if not isinstance(changes, dict):
-                    raise TypeError("For single id, changes must be a dict")
-                od._update(table_schema_name, ids, changes)  # discard representation
-                return None
-            if not isinstance(ids, list):
-                raise TypeError("ids must be str or list[str]")
-            od._update_by_ids(table_schema_name, ids, changes)
-            return None
+        warnings.warn(
+            "client.update() is deprecated. Use client.records.update() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        self.records.update(table_schema_name, ids, changes)
 
     def delete(
         self,
@@ -218,6 +224,9 @@ def delete(
         use_bulk_delete: bool = True,
     ) -> Optional[str]:
         """
+        .. deprecated::
+            Use :meth:`client.records.delete()` instead.
+
         Delete one or more records by GUID.
 
         :param table_schema_name: Schema name of the table (e.g. ``"account"`` or ``"new_MyTestTable"``).
@@ -243,21 +252,11 @@ def delete(
 
                 job_id = client.delete("account", [id1, id2, id3])
         """
-        with self._scoped_odata() as od:
-            if isinstance(ids, str):
-                od._delete(table_schema_name, ids)
-                return None
-            if not isinstance(ids, list):
-                raise TypeError("ids must be str or list[str]")
-            if not ids:
-                return None
-            if not all(isinstance(rid, str) for rid in ids):
-                raise TypeError("ids must contain string GUIDs")
-            if use_bulk_delete:
-                return od._delete_multiple(table_schema_name, ids)
-            for rid in ids:
-                od._delete(table_schema_name, rid)
-            return None
+        warnings.warn(
+            "client.delete() is deprecated. Use client.records.delete() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        return self.records.delete(table_schema_name, ids, use_bulk_delete=use_bulk_delete)
 
     def get(
         self,
@@ -271,6 +270,9 @@ def get(
         page_size: Optional[int] = None,
     ) -> Union[Dict[str, Any], Iterable[List[Dict[str, Any]]]]:
         """
+        .. deprecated::
+            Use :meth:`client.records.get()` or :meth:`client.query.get()` instead.
+
         Fetch a single record by ID or query multiple records.
 
         When ``record_id`` is provided, returns a single record dictionary.
@@ -336,33 +338,24 @@ def get(
                 ):
                     print(f"Batch size: {len(batch)}")
         """
+        warnings.warn(
+            "client.get() is deprecated. Use client.records.get() or client.query.get() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
         if record_id is not None:
-            if not isinstance(record_id, str):
-                raise TypeError("record_id must be str")
-            with self._scoped_odata() as od:
-                return od._get(
-                    table_schema_name,
-                    record_id,
-                    select=select,
-                )
-
-        def _paged() -> Iterable[List[Dict[str, Any]]]:
-            with self._scoped_odata() as od:
-                yield from od._get_multiple(
-                    table_schema_name,
-                    select=select,
-                    filter=filter,
-                    orderby=orderby,
-                    top=top,
-                    expand=expand,
-                    page_size=page_size,
-                )
-
-        return _paged()
+            return self.records.get(table_schema_name, record_id, select=select, expand=expand)
+        else:
+            return self.query.get(
+                table_schema_name, select=select, filter=filter,
+                orderby=orderby, top=top, expand=expand, page_size=page_size,
+            )
 
     # SQL via Web API sql parameter
     def query_sql(self, sql: str):
         """
+        .. deprecated::
+            Use :meth:`client.query.sql()` instead.
+
         Execute a read-only SQL query using the Dataverse Web API ``?sql`` capability.
 
         The SQL query must follow the supported subset: a single SELECT statement with
@@ -394,12 +387,18 @@ def query_sql(self, sql: str):
                 sql = "SELECT a.name, a.telephone1 FROM account AS a WHERE a.statecode = 0"
                 results = client.query_sql(sql)
         """
-        with self._scoped_odata() as od:
-            return od._query_sql(sql)
+        warnings.warn(
+            "client.query_sql() is deprecated. Use client.query.sql() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        return self.query.sql(sql)
 
     # Table metadata helpers
     def get_table_info(self, table_schema_name: str) -> Optional[Dict[str, Any]]:
         """
+        .. deprecated::
+            Use :meth:`client.tables.get()` instead.
+
         Get basic metadata for a table if it exists.
 
         :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"`` or ``"account"``).
@@ -418,8 +417,11 @@ def get_table_info(self, table_schema_name: str) -> Optional[Dict[str, Any]]:
                     print(f"Logical name: {info['table_logical_name']}")
                     print(f"Entity set: {info['entity_set_name']}")
         """
-        with self._scoped_odata() as od:
-            return od._get_table_info(table_schema_name)
+        warnings.warn(
+            "client.get_table_info() is deprecated. Use client.tables.get() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        return self.tables.get(table_schema_name)
 
     def create_table(
         self,
@@ -429,6 +431,9 @@ def create_table(
         primary_column_schema_name: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
+        .. deprecated::
+            Use :meth:`client.tables.create()` instead.
+
         Create a simple custom table with specified columns.
 
         :param table_schema_name: Schema name of the table with customization prefix value (e.g. ``"new_MyTestTable"``).
@@ -489,16 +494,21 @@ class ItemStatus(IntEnum):
                     primary_column_schema_name="new_ProductName"
                 )
         """
-        with self._scoped_odata() as od:
-            return od._create_table(
-                table_schema_name,
-                columns,
-                solution_unique_name,
-                primary_column_schema_name,
-            )
+        warnings.warn(
+            "client.create_table() is deprecated. Use client.tables.create() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        return self.tables.create(
+            table_schema_name, columns,
+            solution=solution_unique_name,
+            primary_column=primary_column_schema_name,
+        )
 
     def delete_table(self, table_schema_name: str) -> None:
         """
+        .. deprecated::
+            Use :meth:`client.tables.delete()` instead.
+
         Delete a custom table by name.
 
         :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"`` or ``"account"``).
@@ -515,11 +525,17 @@ def delete_table(self, table_schema_name: str) -> None:
 
                 client.delete_table("new_MyTestTable")
         """
-        with self._scoped_odata() as od:
-            od._delete_table(table_schema_name)
+        warnings.warn(
+            "client.delete_table() is deprecated. Use client.tables.delete() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        self.tables.delete(table_schema_name)
 
     def list_tables(self) -> list[dict[str, Any]]:
         """
+        .. deprecated::
+            Use :meth:`client.tables.list()` instead.
+
         List all non-private tables in the Dataverse environment.
 
         :return: List of EntityDefinition metadata dictionaries.
@@ -532,15 +548,21 @@ def list_tables(self) -> list[dict[str, Any]]:
                 for table in tables:
                     print(table["LogicalName"])
         """
-        with self._scoped_odata() as od:
-            return od._list_tables()
+        warnings.warn(
+            "client.list_tables() is deprecated. Use client.tables.list() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        return self.tables.list()
 
     def create_columns(
         self,
         table_schema_name: str,
         columns: Dict[str, Any],
     ) -> List[str]:
         """
+        .. deprecated::
+            Use :meth:`client.tables.add_columns()` instead.
+
         Create one or more columns on an existing table using a schema-style mapping.
 
         :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"``).
@@ -564,18 +586,21 @@ def create_columns(
                 )
                 print(created)  # ['new_Scratch', 'new_Flags', 'new_Document']
         """
-        with self._scoped_odata() as od:
-            return od._create_columns(
-                table_schema_name,
-                columns,
-            )
+        warnings.warn(
+            "client.create_columns() is deprecated. Use client.tables.add_columns() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        return self.tables.add_columns(table_schema_name, columns)
 
     def delete_columns(
         self,
         table_schema_name: str,
         columns: Union[str, List[str]],
     ) -> List[str]:
         """
+        .. deprecated::
+            Use :meth:`client.tables.remove_columns()` instead.
+
         Delete one or more columns from a table.
 
         :param table_schema_name: Schema name of the table (e.g. ``"new_MyTestTable"``).
@@ -593,11 +618,11 @@ def delete_columns(
                 )
                 print(removed)  # ['new_Scratch', 'new_Flags']
         """
-        with self._scoped_odata() as od:
-            return od._delete_columns(
-                table_schema_name,
-                columns,
-            )
+        warnings.warn(
+            "client.delete_columns() is deprecated. Use client.tables.remove_columns() instead.",
+            DeprecationWarning, stacklevel=2,
+        )
+        return self.tables.remove_columns(table_schema_name, columns)
 
     # File upload
     def upload_file(
@@ -699,4 +724,4 @@ def flush_cache(self, kind) -> int:
             return od._flush_cache(kind)
 
 
-__all__ = ["DataverseClient"]
+__all__ = ["DataverseClient", "RecordOperations", "QueryOperations", "TableOperations"]

src/PowerPlatform/Dataverse/operations/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Operation namespaces for the Dataverse SDK."""
+
+from .records import RecordOperations
+from .query import QueryOperations
+from .tables import TableOperations
+
+__all__ = ["RecordOperations", "QueryOperations", "TableOperations"]