Add context manager support with HTTP connection pooling

Enable `with DataverseClient(...) as client:` pattern for automatic
resource cleanup and requests.Session-based connection pooling (TCP/TLS
reuse). Adds close() for explicit lifecycle management and closed-state
guards on all operations via _scoped_odata().

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

Author: tpellissier

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,74 @@ 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
+        """
+        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

src/PowerPlatform/Dataverse/data/_odata.py

@@ -116,6 +116,7 @@ def __init__(
         auth,
         base_url: str,
         config=None,
+        session=None,
     ) -> None:
         """Initialize the OData client.
 
@@ -127,6 +128,8 @@ def __init__(
         :type base_url: ``str``
         :param config: Optional Dataverse configuration (HTTP retry, backoff, timeout, language code). If omitted ``DataverseConfig.from_env()`` is used.
         :type config: ~PowerPlatform.Dataverse.core.config.DataverseConfig | ``None``
+        :param session: Optional ``requests.Session`` for HTTP connection pooling.
+        :type session: :class:`requests.Session` | ``None``
         :raises ValueError: If ``base_url`` is empty after stripping.
         """
         self.auth = auth
@@ -144,6 +147,7 @@ def __init__(
             retries=self.config.http_retries,
             backoff=self.config.http_backoff,
             timeout=self.config.http_timeout,
+            session=session,
         )
         # Cache: normalized table_schema_name (lowercase) -> entity set name (plural) resolved from metadata
         self._logical_to_entityset_cache: dict[str, str] = {}
@@ -163,6 +167,18 @@ def _call_scope(self):
         finally:
             _CALL_SCOPE_CORRELATION_ID.reset(token)
 
+    def close(self) -> None:
+        """Close the OData client and release resources.
+
+        Clears all internal caches and closes the underlying HTTP client.
+        Safe to call multiple times.
+        """
+        self._logical_to_entityset_cache.clear()
+        self._logical_primaryid_cache.clear()
+        self._picklist_label_cache.clear()
+        if self._http is not None:
+            self._http.close()
+
     def _headers(self) -> Dict[str, str]:
         """Build standard OData headers with bearer auth."""
         scope = f"{self.base_url}/.default"