Merge branch 'main' into users/sagebree/codmod_fixes

Author: sagebree

.azdo/ci-pr.yaml

@@ -43,7 +43,7 @@ extends:
         - script: |
             python -m pip install --upgrade pip
             python -m pip install flake8 black build diff-cover
-            python -m pip install -e .[dev]
+            python -m pip install -e .[dev,async]
           displayName: 'Install dependencies'
         
         - script: |

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

@@ -19,6 +19,7 @@ This skill provides guidance for developers working on the PowerPlatform Dataver
 4. **Update documentation** when adding features - Keep README and SKILL files (both copies) in sync
 5. **Consider backwards compatibility** - Avoid breaking changes
 6. **Internal vs public naming** - Modules, files, and functions not meant to be part of the public API must use a `_` prefix (e.g., `_odata.py`, `_relationships.py`). Files without the prefix (e.g., `constants.py`, `metadata.py`) are public and importable by SDK consumers
+7. **Async client** - The SDK ships a full async client (`AsyncDataverseClient`) under `src/PowerPlatform/Dataverse/aio/`. When adding a feature to the sync client, add it to the async client too. The async operation namespaces mirror the sync ones: `aio/operations/async_records.py`, `async_query.py`, `async_tables.py`, `async_batch.py`, `async_files.py`. Pure logic (payload builders, URL construction) goes in `data/_odata_base.py` — inherited by both `_ODataClient` and `_AsyncODataClient` — so it only needs to be written once; HTTP-calling code goes in `data/_odata.py` (sync) or `aio/data/_async_odata.py` (async). Async tests live in `tests/unit/aio/` and async examples in `examples/aio/`. The `aiohttp` dependency is an optional extra (`pip install "PowerPlatform-Dataverse-Client[async]"`) — do not move it into the required `dependencies` list in `pyproject.toml`.
 
 ### Dataverse Property Naming Rules
 

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

@@ -588,6 +588,115 @@ except ValidationError as e:
 10. **Test in non-production environments** first
 11. **Use named constants** - Import cascade behavior constants from `PowerPlatform.Dataverse.common.constants`
 
+## Async Client
+
+The SDK ships a full async client, `AsyncDataverseClient`, under `PowerPlatform.Dataverse.aio`. Requires the `[async]` extra: `pip install "PowerPlatform-Dataverse-Client[async]"`.
+
+### Import
+```python
+from azure.identity.aio import DefaultAzureCredential
+from PowerPlatform.Dataverse.aio import AsyncDataverseClient
+```
+
+### Client Initialization
+```python
+# Context manager (recommended -- closes session and clears caches automatically)
+async with AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+    ...  # all operations here
+
+# Standalone (call aclose() in a finally block)
+client = AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential)
+try:
+    ...
+finally:
+    await client.aclose()
+```
+
+### CRUD Operations
+Every sync method has an async equivalent -- add `await`:
+```python
+# Create
+account_id = await client.records.create("account", {"name": "Contoso Ltd"})
+
+# Read
+account = await client.records.retrieve("account", account_id, select=["name", "telephone1"])
+
+# Update
+await client.records.update("account", account_id, {"telephone1": "555-0200"})
+
+# Delete
+await client.records.delete("account", account_id)
+
+# Bulk create
+ids = await client.records.create("account", [{"name": "A"}, {"name": "B"}])
+```
+
+### Query Builder
+```python
+from PowerPlatform.Dataverse.models.filters import col
+
+# Collect all results
+result = await (
+    client.query.builder("account")
+    .select("name", "telephone1")
+    .where(col("statecode") == 0)
+    .top(10)
+    .execute()
+)
+for record in result:
+    print(record["name"])
+
+# Lazy page iteration (memory-efficient)
+async for page in (
+    client.query.builder("account")
+    .select("name")
+    .page_size(500)
+    .execute_pages()
+):
+    for record in page:
+        print(record["name"])
+
+# SQL query
+rows = await client.query.sql("SELECT TOP 5 name FROM account")
+
+# FetchXML
+xml = '<fetch top="5"><entity name="account"><attribute name="name"/></entity></fetch>'
+rows = await client.query.fetchxml(xml).execute()
+```
+
+### Batch and Changesets
+```python
+# Plain batch
+batch = client.batch.new()
+batch.records.create("account", {"name": "Alpha"})
+result = await batch.execute()
+
+# Atomic changeset
+batch = client.batch.new()
+async with batch.changeset() as cs:
+    ref = cs.records.create("contact", {"firstname": "Alice"})
+    cs.records.update("account", account_id, {"primarycontactid@odata.bind": ref})
+result = await batch.execute()
+```
+
+### DataFrame Operations
+```python
+import pandas as pd
+
+# Query to DataFrame
+result = await (
+    client.query.builder("account")
+    .select("name", "telephone1")
+    .where(col("statecode") == 0)
+    .execute()
+)
+df = result.to_dataframe()
+
+# Create from DataFrame
+new_accounts = pd.DataFrame([{"name": "Contoso"}, {"name": "Fabrikam"}])
+ids = await client.dataframe.create("account", new_accounts)
+```
+
 ## Additional Resources
 
 Load these resources as needed during development:

.github/workflows/python-package.yml

@@ -30,7 +30,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install flake8 black build diff-cover
-        python -m pip install -e .[dev]
+        python -m pip install -e .[dev,async]
     
     - name: Check format with black
       run: |

README.md

@@ -16,7 +16,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 - [Key features](#key-features)
 - [Getting started](#getting-started)
   - [Prerequisites](#prerequisites)
-  - [Install the package](#install-the-package)  
+  - [Install the package](#install-the-package)
   - [Authenticate the client](#authenticate-the-client)
 - [Key concepts](#key-concepts)
 - [Examples](#examples)
@@ -30,6 +30,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
   - [Relationship management](#relationship-management)
   - [File operations](#file-operations)
   - [Batch operations](#batch-operations)
+- [Async client](#async-client)
 - [Next steps](#next-steps)
 - [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
@@ -53,7 +54,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 
 ### Prerequisites
 
-- **Python 3.10+** (3.10, 3.11, 3.12, 3.13 supported)  
+- **Python 3.10+** (3.10, 3.11, 3.12, 3.13 supported)
 - **Microsoft Dataverse environment** with appropriate permissions
 - **OAuth authentication configured** for your application
 
@@ -92,7 +93,7 @@ The client requires any Azure Identity `TokenCredential` implementation for OAut
 
 ```python
 from azure.identity import (
-    InteractiveBrowserCredential, 
+    InteractiveBrowserCredential,
     ClientSecretCredential,
     CertificateCredential,
     AzureCliCredential
@@ -103,7 +104,7 @@ from PowerPlatform.Dataverse.client import DataverseClient
 credential = InteractiveBrowserCredential()  # Browser authentication
 # credential = AzureCliCredential()          # If logged in via 'az login'
 
-# Production options  
+# Production options
 # credential = ClientSecretCredential(tenant_id, client_id, client_secret)
 # credential = CertificateCredential(tenant_id, client_id, cert_path)
 
@@ -209,7 +210,7 @@ a PATCH request; multiple items use the `UpsertMultiple` bulk action.
 > upsert requests will be rejected by Dataverse with a 400 error.
 
 ```python
-from PowerPlatform.Dataverse.models.upsert import UpsertItem
+from PowerPlatform.Dataverse.models import UpsertItem
 
 # Upsert a single record
 client.records.upsert("account", [
@@ -346,7 +347,7 @@ query = (client.query.builder("contact")
 For complex logic (OR, NOT, grouping), compose expressions with `&`, `|`, `~`:
 
 ```python
-from PowerPlatform.Dataverse.models.filters import col
+from PowerPlatform.Dataverse.models import col
 
 # OR conditions: (statecode = 0 OR statecode = 1) AND revenue > 100k
 for record in (client.query.builder("account")
@@ -397,7 +398,7 @@ if record:
 **Nested expand with options** -- expand navigation properties with `$select`, `$filter`, `$orderby`, and `$top`:
 
 ```python
-from PowerPlatform.Dataverse.models.query_builder import ExpandOption
+from PowerPlatform.Dataverse.models import ExpandOption
 
 # Expand related tasks with filtering and sorting
 for record in (client.query.builder("account")
@@ -614,12 +615,14 @@ client.tables.delete("new_Product")
 Create relationships between tables using the relationship API. For a complete working example, see [examples/advanced/relationships.py](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/relationships.py).
 
 ```python
-from PowerPlatform.Dataverse.models.relationship import (
+from PowerPlatform.Dataverse.models import (
+    CascadeConfiguration,
+    Label,
+    LocalizedLabel,
     LookupAttributeMetadata,
-    OneToManyRelationshipMetadata,
     ManyToManyRelationshipMetadata,
+    OneToManyRelationshipMetadata,
 )
-from PowerPlatform.Dataverse.models.labels import Label, LocalizedLabel
 
 # Create a one-to-many relationship: Department (1) -> Employee (N)
 # This adds a "Department" lookup field to the Employee table
@@ -783,6 +786,99 @@ result = batch.execute()
 
 For a complete example see [examples/advanced/batch.py](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/batch.py).
 
+## Async client
+
+The SDK ships a full async client, `AsyncDataverseClient`, for use in async applications. It mirrors every operation of the sync client — the same namespaces (`records`, `query`, `tables`, `files`, `batch`), the same method signatures, and the same return types.
+
+### Install
+
+The async client requires `aiohttp`, which is an optional extra:
+
+```bash
+pip install "PowerPlatform-Dataverse-Client[async]"
+```
+
+### Quick start
+
+```python
+import asyncio
+from azure.identity.aio import DefaultAzureCredential
+from PowerPlatform.Dataverse.aio import AsyncDataverseClient
+
+async def main():
+    async with DefaultAzureCredential() as credential:
+        async with AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+            # Create a contact
+            contact_id = await client.records.create("contact", {"firstname": "John", "lastname": "Doe"})
+
+            # Read it back
+            contact = await client.records.retrieve("contact", contact_id, select=["firstname", "lastname"])
+            print(f"Created: {contact['firstname']} {contact['lastname']}")
+
+            # Clean up
+            await client.records.delete("contact", contact_id)
+
+asyncio.run(main())
+```
+
+### Standalone usage (without `async with`)
+
+```python
+client = AsyncDataverseClient("https://yourorg.crm.dynamics.com", credential)
+try:
+    account_id = await client.records.create("account", {"name": "Contoso Ltd"})
+finally:
+    await client.aclose()
+```
+
+### Query builder
+
+The async query builder API is identical to the sync one:
+
+```python
+from PowerPlatform.Dataverse.models.filters import col
+
+# Execute and collect all results
+result = await (
+    client.query.builder("account")
+    .select("name", "telephone1")
+    .where(col("statecode") == 0)
+    .top(10)
+    .execute()
+)
+for record in result:
+    print(record["name"])
+
+# Lazy page-by-page iteration (memory-efficient for large sets)
+async for page in (
+    client.query.builder("account")
+    .select("name")
+    .page_size(500)
+    .execute_pages()
+):
+    for record in page:
+        print(record["name"])
+```
+
+### Batch and changesets
+
+```python
+batch = client.batch.new()
+batch.records.create("account", {"name": "Alpha"})
+batch.records.create("account", {"name": "Beta"})
+result = await batch.execute()
+print(f"Created {len(result.entity_ids)} records")
+
+# Atomic changeset
+batch = client.batch.new()
+async with batch.changeset() as cs:
+    ref = cs.records.create("contact", {"firstname": "Alice"})
+    cs.records.update("account", account_id, {"primarycontactid@odata.bind": ref})
+result = await batch.execute()
+```
+
+See [examples/aio/](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/tree/main/examples/aio) for async equivalents of all sync examples.
+
 ## Next steps
 
 ### More sample code
@@ -808,7 +904,7 @@ For comprehensive information on Microsoft Dataverse and related technologies:
 | Resource | Description |
 |----------|-------------|
 | **[Dataverse Developer Guide](https://learn.microsoft.com/power-apps/developer/data-platform/)** | Complete developer documentation for Microsoft Dataverse |
-| **[Dataverse Web API Reference](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/)** | Detailed Web API reference and examples |  
+| **[Dataverse Web API Reference](https://learn.microsoft.com/power-apps/developer/data-platform/webapi/)** | Detailed Web API reference and examples |
 | **[Azure Identity for Python](https://learn.microsoft.com/python/api/overview/azure/identity-readme)** | Authentication library documentation and credential types |
 | **[Power Platform Developer Center](https://learn.microsoft.com/power-platform/developer/)** | Broader Power Platform development resources |
 | **[Dataverse SDK for .NET](https://learn.microsoft.com/power-apps/developer/data-platform/org-service/overview)** | Official .NET SDK for Microsoft Dataverse |
@@ -862,8 +958,7 @@ Enable file-based HTTP logging to capture all requests and responses for debuggi
 
 ```python
 from PowerPlatform.Dataverse.client import DataverseClient
-from PowerPlatform.Dataverse.core.config import DataverseConfig
-from PowerPlatform.Dataverse.core.log_config import LogConfig
+from PowerPlatform.Dataverse.core import DataverseConfig, LogConfig
 
 log_cfg = LogConfig(
     log_folder="./my_logs",      # Directory for log files (created if missing)

examples/aio/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.