Add context manager support with HTTP connection pooling (#117)

## Summary

- Enable `with DataverseClient(...) as client:` for automatic resource
cleanup and HTTP connection pooling
- Add `close()` method for explicit lifecycle management (idempotent,
safe to call multiple times)
- Thread `requests.Session` through `DataverseClient` → `_ODataClient` →
`_HttpClient` for TCP/TLS reuse
- Guard all operations against use-after-close via `_check_closed()` in
`_scoped_odata()` — raises `RuntimeError("DataverseClient is closed")`
- Clear all internal caches (entity set, primary ID, picklist) on close
- Full backward compatibility: client works identically without `with`
statement

### Files changed
- `src/PowerPlatform/Dataverse/core/_http.py` — session parameter +
`close()`
- `src/PowerPlatform/Dataverse/data/_odata.py` — session threading +
`close()` with cache clearing
- `src/PowerPlatform/Dataverse/client.py` —
`__enter__`/`__exit__`/`close()`/`_check_closed()`
- `tests/unit/test_context_manager.py` — 34 new tests (protocol, session
lifecycle, close behavior, closed-state guards, backward compat,
exception handling)

## Test plan
- [x] 34 new unit tests covering all context manager behavior
- [x] Full test suite passes (195/195)
- [ ] Manual verification with live Dataverse environment

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

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-use/SKILL.md

@@ -53,7 +53,13 @@ credential = AzureCliCredential()
 credential = ClientSecretCredential(tenant_id, client_id, client_secret)
 credential = CertificateCredential(tenant_id, client_id, cert_path)
 
-# Create client (no trailing slash on URL!)
+# Create client with context manager (recommended -- enables HTTP connection pooling)
+# No trailing slash on URL!
+with DataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+    ...  # all operations here
+# Session closed, caches cleared automatically
+
+# Or without context manager:
 client = DataverseClient("https://yourorg.crm.dynamics.com", credential)
 ```
 

README.md

@@ -113,6 +113,7 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 | Concept | Description |
 |---------|-------------|
 | **DataverseClient** | Main entry point; provides `records`, `query`, `tables`, and `files` namespaces |
+| **Context Manager** | Use `with DataverseClient(...) as client:` for automatic cleanup and HTTP connection pooling |
 | **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (query & search), `client.tables` (metadata), and `client.files` (file uploads) |
 | **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) |
@@ -131,17 +132,18 @@ from PowerPlatform.Dataverse.client import DataverseClient
 
 # Connect to Dataverse
 credential = InteractiveBrowserCredential()
-client = DataverseClient("https://yourorg.crm.dynamics.com", credential)
 
-# Create a contact
-contact_id = client.records.create("contact", {"firstname": "John", "lastname": "Doe"})
+with DataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+    # Create a contact
+    contact_id = client.records.create("contact", {"firstname": "John", "lastname": "Doe"})
 
-# Read the contact back
-contact = client.records.get("contact", contact_id, select=["firstname", "lastname"])
-print(f"Created: {contact['firstname']} {contact['lastname']}")
+    # Read the contact back
+    contact = client.records.get("contact", contact_id, select=["firstname", "lastname"])
+    print(f"Created: {contact['firstname']} {contact['lastname']}")
 
-# Clean up
-client.records.delete("contact", contact_id)
+    # Clean up
+    client.records.delete("contact", contact_id)
+# Session closed, caches cleared automatically
 ```
 
 ### Basic CRUD operations

examples/advanced/file_upload.py

@@ -375,4 +375,5 @@ def get_dataset_info(file_path: Path):
     except Exception as e:  # noqa: BLE001
         print({"test_file_8mb_deleted": False, "error": str(e)})
 
+client.close()
 print("Done.")

examples/advanced/relationships.py

@@ -108,11 +108,6 @@ def backoff(op, *, delays=(0, 2, 5, 10, 20, 20)):
 
 
 def main():
-    # Initialize relationship IDs to None for cleanup safety
-    rel_id_1 = None
-    rel_id_2 = None
-    rel_id_3 = None
-
     print("=" * 80)
     print("Dataverse SDK - Relationship Management Example")
     print("=" * 80)
@@ -135,8 +130,16 @@ def main():
     credential = InteractiveBrowserCredential()
 
     log_call(f"DataverseClient(base_url='{base_url}', credential=...)")
-    client = DataverseClient(base_url=base_url, credential=credential)
-    print(f"[OK] Connected to: {base_url}")
+    with DataverseClient(base_url=base_url, credential=credential) as client:
+        print(f"[OK] Connected to: {base_url}")
+        _run_example(client)
+
+
+def _run_example(client):
+    # Initialize relationship IDs to None for cleanup safety
+    rel_id_1 = None
+    rel_id_2 = None
+    rel_id_3 = None
 
     # ============================================================================
     # 2. CLEANUP PREVIOUS RUN (Idempotency)

examples/advanced/walkthrough.py

@@ -87,9 +87,12 @@ def main():
     credential = InteractiveBrowserCredential()
 
     log_call(f"DataverseClient(base_url='{base_url}', credential=...)")
-    client = DataverseClient(base_url=base_url, credential=credential)
-    print(f"[OK] Connected to: {base_url}")
+    with DataverseClient(base_url=base_url, credential=credential) as client:
+        print(f"[OK] Connected to: {base_url}")
+        _run_walkthrough(client)
 
+
+def _run_walkthrough(client):
     # ============================================================================
     # 2. TABLE CREATION (METADATA)
     # ============================================================================

examples/basic/installation_example.py

@@ -205,11 +205,12 @@ def show_usage_examples():
 # Set up authentication
 credential = InteractiveBrowserCredential()
 
-# Create client
-client = DataverseClient(
-    "https://yourorg.crm.dynamics.com",
-    credential
-)
+# Recommended: use context manager for connection pooling and automatic cleanup
+with DataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+    ...  # all operations here
+
+# Or without context manager:
+client = DataverseClient("https://yourorg.crm.dynamics.com", credential)
 ```
 
 CRUD Operations:
@@ -307,19 +308,18 @@ def interactive_test():
         credential = InteractiveBrowserCredential()
 
         print("  Creating client...")
-        client = DataverseClient(org_url.rstrip("/"), credential)
-
-        print("  Testing connection...")
-        tables = client.tables.list()
-        print(f"  [OK] Connection successful!")
-        print(f"  Found {len(tables)} tables in environment")
-
-        custom_tables = client.tables.list(
-            filter="IsCustomEntity eq true",
-            select=["LogicalName", "SchemaName"],
-        )
-        print(f"  Found {len(custom_tables)} custom tables (filter + select)")
-        print(f"  Connected to: {org_url}")
+        with DataverseClient(org_url.rstrip("/"), credential) as client:
+            print("  Testing connection...")
+            tables = client.tables.list()
+            print(f"  [OK] Connection successful!")
+            print(f"  Found {len(tables)} tables in environment")
+
+            custom_tables = client.tables.list(
+                filter="IsCustomEntity eq true",
+                select=["LogicalName", "SchemaName"],
+            )
+            print(f"  Found {len(custom_tables)} custom tables (filter + select)")
+            print(f"  Connected to: {org_url}")
 
         print("\n  Your SDK is ready for use!")
         print("  Check the usage examples above for common patterns")

src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-use/SKILL.md

@@ -53,7 +53,13 @@ credential = AzureCliCredential()
 credential = ClientSecretCredential(tenant_id, client_id, client_secret)
 credential = CertificateCredential(tenant_id, client_id, cert_path)
 
-# Create client (no trailing slash on URL!)
+# Create client with context manager (recommended -- enables HTTP connection pooling)
+# No trailing slash on URL!
+with DataverseClient("https://yourorg.crm.dynamics.com", credential) as client:
+    ...  # all operations here
+# Session closed, caches cleared automatically
+
+# Or without context manager:
 client = DataverseClient("https://yourorg.crm.dynamics.com", credential)
 ```
 

src/PowerPlatform/Dataverse/client.py

@@ -7,6 +7,8 @@
 from contextlib import contextmanager
 from typing import Any, Dict, Iterable, Iterator, List, Optional, Union
 
+import requests
+
 from azure.core.credentials import TokenCredential
 
 from .core._auth import _AuthManager
@@ -59,31 +61,29 @@ class DataverseClient:
     - ``client.tables`` -- table and column metadata management
     - ``client.files`` -- file upload operations
 
+    The client supports Python's context manager protocol for automatic resource
+    cleanup and HTTP connection pooling:
+
     Example:
-        Create a client and perform basic operations::
+        **Recommended -- context manager** (enables HTTP connection pooling)::
 
             from azure.identity import InteractiveBrowserCredential
             from PowerPlatform.Dataverse.client import DataverseClient
 
             credential = InteractiveBrowserCredential()
-            client = DataverseClient(
-                "https://org.crm.dynamics.com",
-                credential
-            )
 
-            # Create a record
-            record_id = client.records.create("account", {"name": "Contoso Ltd"})
+            with DataverseClient("https://org.crm.dynamics.com", credential) as client:
+                record_id = client.records.create("account", {"name": "Contoso Ltd"})
+                client.records.update("account", record_id, {"telephone1": "555-0100"})
+            # Session closed, caches cleared automatically
 
-            # Update a record
-            client.records.update("account", record_id, {"telephone1": "555-0100"})
+        **Manual lifecycle**::
 
-            # Query records
-            for page in client.records.get("account", filter="name eq 'Contoso Ltd'"):
-                for account in page:
-                    print(account["name"])
-
-            # Delete a record
-            client.records.delete("account", record_id)
+            client = DataverseClient("https://org.crm.dynamics.com", credential)
+            try:
+                record_id = client.records.create("account", {"name": "Contoso Ltd"})
+            finally:
+                client.close()
     """
 
     def __init__(
@@ -98,6 +98,8 @@ def __init__(
             raise ValueError("base_url is required.")
         self._config = config or DataverseConfig.from_env()
         self._odata: Optional[_ODataClient] = None
+        self._session: Optional[requests.Session] = None
+        self._closed: bool = False
 
         # Operation namespaces
         self.records = RecordOperations(self)
@@ -120,16 +122,77 @@ def _get_odata(self) -> _ODataClient:
                 self.auth,
                 self._base_url,
                 self._config,
+                session=self._session,
             )
         return self._odata
 
     @contextmanager
     def _scoped_odata(self) -> Iterator[_ODataClient]:
         """Yield the low-level client while ensuring a correlation scope is active."""
+        self._check_closed()
         od = self._get_odata()
         with od._call_scope():
             yield od
 
+    # ---------------- Context manager / lifecycle ----------------
+
+    def __enter__(self) -> DataverseClient:
+        """Enter the context manager.
+
+        Creates a :class:`requests.Session` for HTTP connection pooling.
+        All operations within the ``with`` block reuse this session for
+        better performance (TCP and TLS reuse).
+
+        :return: The client instance.
+        :rtype: DataverseClient
+
+        :raises RuntimeError: If the client has been closed.
+        """
+        self._check_closed()
+        if self._session is None:
+            self._session = requests.Session()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the context manager with cleanup.
+
+        Calls :meth:`close` to release resources. Exceptions are not
+        suppressed.
+        """
+        self.close()
+
+    def close(self) -> None:
+        """Close the client and release resources.
+
+        Closes the HTTP session (if any), clears internal caches, and
+        marks the client as closed. Safe to call multiple times. After
+        closing, any operation will raise :class:`RuntimeError`.
+
+        Called automatically when using the client as a context manager.
+
+        Example::
+
+            client = DataverseClient(base_url, credential)
+            try:
+                client.records.create("account", {"name": "Contoso"})
+            finally:
+                client.close()
+        """
+        if self._closed:
+            return
+        if self._odata is not None:
+            self._odata.close()
+            self._odata = None
+        if self._session is not None:
+            self._session.close()
+            self._session = None
+        self._closed = True
+
+    def _check_closed(self) -> None:
+        """Raise :class:`RuntimeError` if the client has been closed."""
+        if self._closed:
+            raise RuntimeError("DataverseClient is closed")
+
     # ---------------- Unified CRUD: create/update/delete ----------------
     def create(self, table_schema_name: str, records: Union[Dict[str, Any], List[Dict[str, Any]]]) -> List[str]:
         """

src/PowerPlatform/Dataverse/core/_http.py

@@ -30,17 +30,23 @@ class _HttpClient:
     :type backoff: :class:`float` | None
     :param timeout: Default request timeout in seconds. If None, uses per-method defaults.
     :type timeout: :class:`float` | None
+    :param session: Optional ``requests.Session`` for HTTP connection pooling.
+        When provided, all requests use this session (enabling TCP/TLS reuse).
+        When ``None``, each request uses ``requests.request()`` directly.
+    :type session: :class:`requests.Session` | None
     """
 
     def __init__(
         self,
         retries: Optional[int] = None,
         backoff: Optional[float] = None,
         timeout: Optional[float] = None,
+        session: Optional[requests.Session] = None,
     ) -> None:
         self.max_attempts = retries if retries is not None else 5
         self.base_delay = backoff if backoff is not None else 0.5
         self.default_timeout: Optional[float] = timeout
+        self._session = session
 
     def _request(self, method: str, url: str, **kwargs: Any) -> requests.Response:
         """
@@ -68,12 +74,22 @@ def _request(self, method: str, url: str, **kwargs: Any) -> requests.Response:
                 kwargs["timeout"] = 120 if m in ("post", "delete") else 10
 
         # Small backoff retry on network errors only
+        requester = self._session.request if self._session is not None else requests.request
         for attempt in range(self.max_attempts):
             try:
-                return requests.request(method, url, **kwargs)
+                return requester(method, url, **kwargs)
             except requests.exceptions.RequestException:
                 if attempt == self.max_attempts - 1:
                     raise
                 delay = self.base_delay * (2**attempt)
                 time.sleep(delay)
                 continue
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources.
+
+        If a session was provided, closes it. Safe to call multiple times.
+        """
+        if self._session is not None:
+            self._session.close()
+            self._session = None