Add operation namespaces (client.records, client.query, client.tables) (microsoft#102)

* 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>

* 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 (microsoft#8)
- Add :raises: for HttpError, ValidationError, ValueError across all
  operation methods (microsoft#6)
- Fix query.sql() to document ValidationError instead of incorrect
  SQLParseError
- Restore post-call validation in records.create() matching original
  client.create() behavior (microsoft#9)
- Improve deprecated get() docstring with explicit guidance on when to
  use records.get() vs query.get() (microsoft#10)

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

* Use :class: role in :type:/:rtype: directives for Sphinx cross-references

Aligns with existing codebase convention and ensures clickable
hyperlinks in generated API documentation.

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

---------

Co-authored-by: tpellissier <tpellissier@microsoft.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

.claude/skills/dataverse-sdk-dev/SKILL.md

@@ -13,7 +13,7 @@ This skill provides guidance for developers working on the PowerPlatform Dataver
 
 ### API Design
 
-1. **All public methods in client.py** - Public API methods must be in client.py
+1. **Public API in operation namespaces** - New public methods go in the appropriate namespace module under `src/PowerPlatform/Dataverse/operations/` (`records.py`, `query.py`, `tables.py`). The `client.py` file exposes these via namespace properties (`client.records`, `client.query`, `client.tables`)
 2. **Every public method needs README example** - Public API methods must have examples in README.md
 3. **Reuse existing APIs** - Always check if an existing method can be used before making direct Web API calls
 4. **Update documentation** when adding features - Keep README and SKILL files (both copies) in sync
@@ -25,5 +25,5 @@ This skill provides guidance for developers working on the PowerPlatform Dataver
 7. **Standardize output format** - Use `[INFO]`, `[WARN]`, `[ERR]`, `[OK]` prefixes for console output
 8. **No noqa comments** - Do not add `# noqa: BLE001` or similar linter suppression comments
 9. **Document public APIs** - Add Sphinx-style docstrings with examples for public methods
-10. **Define __all__ in module files, not __init__.py** - Use `__all__` to control exports in the actual module file (e.g., errors.py), not in `__init__.py`.
-11. **Run black before committing** - Always run `python -m black <changed files>` before committing. CI will reject unformatted code. Config is in `pyproject.toml` under `[tool.black]`.
+10. **Define __all__ in module files** - Each module declares its own exports via `__all__` (e.g., `errors.py` defines `__all__ = ["HttpError", ...]`). Package `__init__.py` files should not re-export or redefine another module's `__all__`; they use `__all__ = []` to indicate no star-import exports.
+11. **Run black before committing** - Always run `python -m black <changed files>` before committing. CI will reject unformatted code. Config is in `pyproject.toml` under `[tool.black]`.

README.md

@@ -109,9 +109,10 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 
 | Concept | Description |
 |---------|-------------|
-| **DataverseClient** | Main entry point for all operations with environment connection |
+| **DataverseClient** | Main entry point; provides `records`, `query`, and `tables` namespaces |
+| **Namespaces** | Operations are organized into `client.records` (CRUD), `client.query` (queries), and `client.tables` (metadata) |
 | **Records** | Dataverse records represented as Python dictionaries with column schema names |
-| **Schema names** | Use table schema names (`"account"`, `"new_MyTestTable"`) and column schema names (`"name"`, `"new_MyTestColumn"`). See: [Table definitions in Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/entity-metadata) |  
+| **Schema names** | Use table schema names (`"account"`, `"new_MyTestTable"`) and column schema names (`"name"`, `"new_MyTestColumn"`). See: [Table definitions in Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/entity-metadata) |
 | **Bulk Operations** | Efficient bulk processing for multiple records with automatic optimization |
 | **Paging** | Automatic handling of large result sets with iterators |
 | **Structured Errors** | Detailed exception hierarchy with retry guidance and diagnostic information |
@@ -130,32 +131,31 @@ credential = InteractiveBrowserCredential()
 client = DataverseClient("https://yourorg.crm.dynamics.com", credential)
 
 # Create a contact
-contact_id = client.create("contact", {"firstname": "John", "lastname": "Doe"})[0]
+contact_id = client.records.create("contact", {"firstname": "John", "lastname": "Doe"})
 
 # Read the contact back
-contact = client.get("contact", contact_id, select=["firstname", "lastname"])
+contact = client.records.get("contact", contact_id, select=["firstname", "lastname"])
 print(f"Created: {contact['firstname']} {contact['lastname']}")
 
 # Clean up
-client.delete("contact", contact_id)
+client.records.delete("contact", contact_id)
 ```
 
 ### Basic CRUD operations
 
 ```python
 # Create a record
-account_ids = client.create("account", {"name": "Contoso Ltd"})
-account_id = account_ids[0]
+account_id = client.records.create("account", {"name": "Contoso Ltd"})
 
 # Read a record
-account = client.get("account", account_id)
+account = client.records.get("account", account_id)
 print(account["name"])
 
 # Update a record
-client.update("account", account_id, {"telephone1": "555-0199"})
+client.records.update("account", account_id, {"telephone1": "555-0199"})
 
 # Delete a record
-client.delete("account", account_id)
+client.records.delete("account", account_id)
 ```
 
 ### Bulk operations
@@ -167,45 +167,43 @@ payloads = [
     {"name": "Company B"},
     {"name": "Company C"}
 ]
-ids = client.create("account", payloads)
+ids = client.records.create("account", payloads)
 
 # Bulk update (broadcast same change to all)
-client.update("account", ids, {"industry": "Technology"})
+client.records.update("account", ids, {"industry": "Technology"})
 
 # Bulk delete
-client.delete("account", ids, use_bulk_delete=True)
+client.records.delete("account", ids, use_bulk_delete=True)
 ```
 
 ### Query data
 
 ```python
 # SQL query (read-only)
-results = client.query_sql(
+results = client.query.sql(
     "SELECT TOP 10 accountid, name FROM account WHERE statecode = 0"
 )
 for record in results:
     print(record["name"])
 
 # OData query with paging
 # Note: filter and expand parameters are case sensitive
-pages = client.get(
+for page in client.query.get(
     "account",
     select=["accountid", "name"],  # select is case-insensitive (automatically lowercased)
     filter="statecode eq 0",       # filter must use lowercase logical names (not transformed)
-    top=100
-)
-for page in pages:
+    top=100,
+):
     for record in page:
         print(record["name"])
 
 # Query with navigation property expansion (case-sensitive!)
-pages = client.get(
+for page in client.query.get(
     "account",
     select=["name"],
     expand=["primarycontactid"],  # Navigation property names are case-sensitive
-    filter="statecode eq 0"       # Column names must be lowercase logical names
-)
-for page in pages:
+    filter="statecode eq 0",      # Column names must be lowercase logical names
+):
     for account in page:
         contact = account.get("primarycontactid", {})
         print(f"{account['name']} - Contact: {contact.get('fullname', 'N/A')}")
@@ -220,41 +218,41 @@ for page in pages:
 
 ```python
 # Create a custom table, including the customization prefix value in the schema names for the table and columns.
-table_info = client.create_table("new_Product", {
+table_info = client.tables.create("new_Product", {
     "new_Code": "string",
-    "new_Price": "decimal", 
+    "new_Price": "decimal",
     "new_Active": "bool"
 })
 
 # Create with custom primary column name and solution assignment
-table_info = client.create_table(
-    table_schema_name="new_Product",
+table_info = client.tables.create(
+    "new_Product",
     columns={
         "new_Code": "string",
         "new_Price": "decimal"
     },
-    solution_unique_name="MyPublisher",  # Optional: add to specific solution
-    primary_column_schema_name="new_ProductName"  # Optional: custom primary column (default is "{customization prefix value}_Name")
+    solution="MyPublisher",  # Optional: add to specific solution
+    primary_column="new_ProductName",  # Optional: custom primary column (default is "{customization prefix value}_Name")
 )
 
 # Get table information
-info = client.get_table_info("new_Product")
+info = client.tables.get("new_Product")
 print(f"Logical name: {info['table_logical_name']}")
 print(f"Entity set: {info['entity_set_name']}")
 
 # List all tables
-tables = client.list_tables()
+tables = client.tables.list()
 for table in tables:
     print(table)
 
 # Add columns to existing table (columns must include customization prefix value)
-client.create_columns("new_Product", {"new_Category": "string"})
+client.tables.add_columns("new_Product", {"new_Category": "string"})
 
 # Remove columns
-client.delete_columns("new_Product", ["new_Category"])
+client.tables.remove_columns("new_Product", ["new_Category"])
 
 # Clean up
-client.delete_table("new_Product")
+client.tables.delete("new_Product")
 ```
 
 > **Important**: All custom column names must include the customization prefix value (e.g., `"new_"`). 
@@ -311,7 +309,7 @@ from PowerPlatform.Dataverse.client import DataverseClient
 from PowerPlatform.Dataverse.core.errors import HttpError, ValidationError
 
 try:
-    client.get("account", "invalid-id")
+    client.records.get("account", "invalid-id")
 except HttpError as e:
     print(f"HTTP {e.status_code}: {e.message}")
     print(f"Error code: {e.code}")
@@ -335,7 +333,7 @@ For optimal performance in production environments:
 
 | Best Practice | Description |
 |---------------|-------------|
-| **Bulk Operations** | Pass lists to `create()`, `update()` for automatic bulk processing, for `delete()`, set `use_bulk_delete` when passing lists to use bulk operation |
+| **Bulk Operations** | Pass lists to `records.create()`, `records.update()` for automatic bulk processing, for `records.delete()`, set `use_bulk_delete` when passing lists to use bulk operation |
 | **Select Fields** | Specify `select` parameter to limit returned columns and reduce payload size |
 | **Page Size Control** | Use `top` and `page_size` parameters to control memory usage |
 | **Connection Reuse** | Reuse `DataverseClient` instances across operations |
@@ -367,7 +365,7 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 
 When contributing new features to this SDK, please follow these guidelines:
 
-1. **All public methods in client.py** - Public API methods must be defined in [client.py](src/PowerPlatform/Dataverse/client.py)
+1. **Public API in operation namespaces** - New public methods go in the appropriate namespace module under [operations/](src/PowerPlatform/Dataverse/operations/)
 2. **Add README example for public methods** - Add usage examples to this README for public API methods
 3. **Document public APIs** - Include Sphinx-style docstrings with parameter descriptions and examples for all public methods
 4. **Update documentation** when adding features - Keep README and SKILL files (note that each skill has 2 copies) in sync

examples/advanced/file_upload.py

@@ -185,12 +185,12 @@ def backoff(op, *, delays=(0, 2, 5, 10, 20, 20)):
 
 def ensure_table():
     # Check by schema
-    existing = backoff(lambda: client.get_table_info(TABLE_SCHEMA_NAME))
+    existing = backoff(lambda: client.tables.get(TABLE_SCHEMA_NAME))
     if existing:
         print({"table": TABLE_SCHEMA_NAME, "existed": True})
         return existing
-    log(f"client.create_table('{TABLE_SCHEMA_NAME}', schema={{'new_Title': 'string'}})")
-    info = backoff(lambda: client.create_table(TABLE_SCHEMA_NAME, {"new_Title": "string"}))
+    log(f"client.tables.create('{TABLE_SCHEMA_NAME}', schema={{'new_Title': 'string'}})")
+    info = backoff(lambda: client.tables.create(TABLE_SCHEMA_NAME, {"new_Title": "string"}))
     print({"table": TABLE_SCHEMA_NAME, "existed": False, "metadata_id": info.get("metadata_id")})
     return info
 
@@ -213,12 +213,8 @@ def ensure_table():
 record_id = None
 try:
     payload = {name_attr: "File Sample Record"}
-    log(f"client.create('{table_schema_name}', payload)")
-    created_ids = backoff(lambda: client.create(table_schema_name, payload))
-    if isinstance(created_ids, list) and created_ids:
-        record_id = created_ids[0]
-    else:
-        raise RuntimeError("Unexpected create return; expected list[str] with at least one GUID")
+    log(f"client.records.create('{table_schema_name}', payload)")
+    record_id = backoff(lambda: client.records.create(table_schema_name, payload))
     print({"record_created": True, "id": record_id, "table schema name": table_schema_name})
 except Exception as e:  # noqa: BLE001
     print({"record_created": False, "error": str(e)})
@@ -386,8 +382,8 @@ def get_dataset_info(file_path: Path):
 # --------------------------- Cleanup ---------------------------
 if cleanup_record and record_id:
     try:
-        log(f"client.delete('{table_schema_name}', '{record_id}')")
-        backoff(lambda: client.delete(table_schema_name, record_id))
+        log(f"client.records.delete('{table_schema_name}', '{record_id}')")
+        backoff(lambda: client.records.delete(table_schema_name, record_id))
         print({"record_deleted": True})
     except Exception as e:  # noqa: BLE001
         print({"record_deleted": False, "error": str(e)})
@@ -396,8 +392,8 @@ def get_dataset_info(file_path: Path):
 
 if cleanup_table:
     try:
-        log(f"client.delete_table('{TABLE_SCHEMA_NAME}')")
-        backoff(lambda: client.delete_table(TABLE_SCHEMA_NAME))
+        log(f"client.tables.delete('{TABLE_SCHEMA_NAME}')")
+        backoff(lambda: client.tables.delete(TABLE_SCHEMA_NAME))
         print({"table_deleted": True})
     except Exception as e:  # noqa: BLE001
         print({"table_deleted": False, "error": str(e)})