Merge branch 'main' into user/tpellissier/prefix-with-schemaname

Author: tpellissier

src/PowerPlatform/Dataverse/__init__.py

@@ -1,48 +1,6 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT license.
 
-"""
-Microsoft Dataverse SDK for Python.
-
-This package provides a high-level Python client for interacting with Microsoft Dataverse
-environments through the Web API. It supports CRUD operations, SQL queries, table metadata
-management, and file uploads with Azure Identity authentication.
-
-Key Features:
-    - OData CRUD operations (create, read, update, delete)
-    - SQL query support via Web API
-    - Table metadata operations (create, inspect, delete custom tables)
-    - File column upload capabilities
-    - Pandas integration for DataFrame-based operations
-    - Azure Identity credential support
-
-.. note::
-    This SDK requires Azure Identity credentials for authentication. See the
-    `Azure Identity documentation <https://learn.microsoft.com/python/api/overview/azure/identity-readme>`_
-    for supported credential types.
-
-Example:
-    Basic client initialization and usage::
-
-        from azure.identity import InteractiveBrowserCredential
-        from PowerPlatform.Dataverse import DataverseClient
-
-        credential = InteractiveBrowserCredential()
-        client = DataverseClient(
-            "https://org.crm.dynamics.com",
-            credential
-        )
-
-        # Create a record
-        account_id = client.create("account", {"name": "Contoso"})[0]
-
-        # Query records
-        accounts = client.get("account", filter="name eq 'Contoso'")
-        for batch in accounts:
-            for record in batch:
-                print(record["name"])
-"""
-
 from .__version__ import __version__
 from .client import DataverseClient
 

src/PowerPlatform/Dataverse/client.py

@@ -3,6 +3,14 @@
 
 from __future__ import annotations
 
+"""
+Authentication helpers for Dataverse.
+
+This module provides :class:`~PowerPlatform.Dataverse.core.auth.AuthManager`, a thin wrapper over any Azure Identity
+``TokenCredential`` for acquiring OAuth2 access tokens, and :class:`~PowerPlatform.Dataverse.core.auth.TokenPair` for
+storing the acquired token alongside its scope.
+"""
+
 from dataclasses import dataclass
 
 from azure.core.credentials import TokenCredential
@@ -14,9 +22,9 @@ class TokenPair:
     Container for an OAuth2 access token and its associated resource scope.
 
     :param resource: The OAuth2 scope/resource for which the token was acquired.
-    :type resource: str
+    :type resource: ``str``
     :param access_token: The access token string.
-    :type access_token: str
+    :type access_token: ``str``
     """
     resource: str
     access_token: str
@@ -43,7 +51,7 @@ def acquire_token(self, scope: str) -> TokenPair:
         Acquire an access token for the specified OAuth2 scope.
 
         :param scope: OAuth2 scope string, typically ``"https://<org>.crm.dynamics.com/.default"``.
-        :type scope: str
+        :type scope: ``str``
         :return: Token pair containing the scope and access token.
         :rtype: ~PowerPlatform.Dataverse.core.auth.TokenPair
         :raises ~azure.core.exceptions.ClientAuthenticationError: If token acquisition fails.

src/PowerPlatform/Dataverse/core/auth.py

@@ -3,6 +3,14 @@
 
 from __future__ import annotations
 
+"""
+Dataverse client configuration.
+
+Provides :class:`~PowerPlatform.Dataverse.core.config.DataverseConfig`, a lightweight
+immutable container for locale and (reserved) HTTP tuning options plus the
+convenience constructor :meth:`~PowerPlatform.Dataverse.core.config.DataverseConfig.from_env`.
+"""
+
 from dataclasses import dataclass
 from typing import Optional
 
@@ -13,13 +21,13 @@ class DataverseConfig:
     Configuration settings for Dataverse client operations.
 
     :param language_code: LCID (Locale ID) for localized labels and messages. Default is 1033 (English - United States).
-    :type language_code: int
+    :type language_code: ``int``
     :param http_retries: Optional maximum number of retry attempts for transient HTTP errors. Reserved for future use.
-    :type http_retries: int or None
+    :type http_retries: ``int`` | ``None``
     :param http_backoff: Optional backoff multiplier (in seconds) between retry attempts. Reserved for future use.
-    :type http_backoff: float or None
+    :type http_backoff: ``float`` | ``None``
     :param http_timeout: Optional request timeout in seconds. Reserved for future use.
-    :type http_timeout: float or None
+    :type http_timeout: ``float`` | ``None``
     """
     language_code: int = 1033
 

src/PowerPlatform/Dataverse/core/config.py

@@ -81,9 +81,9 @@ def http_subcode(status: int) -> str:
     Convert HTTP status code to error subcode string.
     
     :param status: HTTP status code (e.g., 400, 404, 500).
-    :type status: int
+    :type status: ``int``
     :return: Error subcode string (e.g., "http_400", "http_404").
-    :rtype: str
+    :rtype: ``str``
     """
     return HTTP_STATUS_TO_SUBCODE.get(status, f"http_{status}")
 
@@ -95,8 +95,8 @@ def is_transient_status(status: int) -> bool:
     503 (Service Unavailable), and 504 (Gateway Timeout).
     
     :param status: HTTP status code to check.
-    :type status: int
+    :type status: ``int``
     :return: True if the status code is considered transient.
-    :rtype: bool
+    :rtype: ``bool``
     """
     return status in TRANSIENT_STATUS

src/PowerPlatform/Dataverse/core/error_codes.py

@@ -1,6 +1,17 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT license.
 
+"""
+Structured Dataverse exception hierarchy.
+
+This module provides :class:`~PowerPlatform.Dataverse.core.errors.DataverseError` and
+specialized :class:`~PowerPlatform.Dataverse.core.errors.ValidationError`,
+:class:`~PowerPlatform.Dataverse.core.errors.MetadataError`,
+:class:`~PowerPlatform.Dataverse.core.errors.SQLParseError`, and
+:class:`~PowerPlatform.Dataverse.core.errors.HttpError` for validation, metadata,
+SQL parsing, and Web API HTTP failures.
+"""
+
 from __future__ import annotations
 from typing import Any, Dict, Optional
 import datetime as _dt
@@ -10,24 +21,23 @@ class DataverseError(Exception):
     Base structured exception for the Dataverse SDK.
 
     :param message: Human-readable error message.
-    :type message: str
+    :type message: ``str``
     :param code: Error category code (e.g. ``"validation_error"``, ``"http_error"``).
-    :type code: str
+    :type code: ``str``
     :param subcode: Optional subcategory or specific error identifier.
-    :type subcode: str or None
+    :type subcode: ``str`` | ``None``
     :param status_code: Optional HTTP status code if the error originated from an HTTP response.
-    :type status_code: int or None
+    :type status_code: ``int`` | ``None``
     :param details: Optional dictionary containing additional diagnostic information.
-    :type details: dict or None
+    :type details: ``dict`` | ``None``
     :param source: Error source, either ``"client"`` or ``"server"``.
-    :type source: str
+    :type source: ``str``
     :param is_transient: Whether the error is potentially transient and may succeed on retry.
-    :type is_transient: bool
+    :type is_transient: ``bool``
     """
     def __init__(
         self,
         message: str,
-        *,
         code: str,
         subcode: Optional[str] = None,
         status_code: Optional[int] = None,
@@ -50,7 +60,7 @@ def to_dict(self) -> Dict[str, Any]:
         Convert the error to a dictionary representation.
 
         :return: Dictionary containing all error properties.
-        :rtype: dict
+        :rtype: ``dict``
         """
         return {
             "message": self.message,
@@ -71,11 +81,11 @@ class ValidationError(DataverseError):
     Exception raised for client-side validation failures.
 
     :param message: Human-readable validation error message.
-    :type message: str
+    :type message: ``str``
     :param subcode: Optional specific validation error identifier.
-    :type subcode: str or None
+    :type subcode: ``str`` | ``None``
     :param details: Optional dictionary with additional validation context.
-    :type details: dict or None
+    :type details: ``dict`` | ``None``
     """
     def __init__(self, message: str, *, subcode: Optional[str] = None, details: Optional[Dict[str, Any]] = None):
         super().__init__(message, code="validation_error", subcode=subcode, details=details, source="client")
@@ -85,11 +95,11 @@ class MetadataError(DataverseError):
     Exception raised for metadata operation failures.
 
     :param message: Human-readable metadata error message.
-    :type message: str
+    :type message: ``str``
     :param subcode: Optional specific metadata error identifier.
-    :type subcode: str or None
+    :type subcode: ``str`` | ``None``
     :param details: Optional dictionary with additional metadata context.
-    :type details: dict or None
+    :type details: ``dict`` | ``None``
     """
     def __init__(self, message: str, *, subcode: Optional[str] = None, details: Optional[Dict[str, Any]] = None):
         super().__init__(message, code="metadata_error", subcode=subcode, details=details, source="client")
@@ -99,11 +109,11 @@ class SQLParseError(DataverseError):
     Exception raised for SQL query parsing failures.
 
     :param message: Human-readable SQL parsing error message.
-    :type message: str
+    :type message: ``str``
     :param subcode: Optional specific SQL parsing error identifier.
-    :type subcode: str or None
+    :type subcode: ``str`` | ``None``
     :param details: Optional dictionary with SQL query context and parse information.
-    :type details: dict or None
+    :type details: ``dict`` | ``None``
     """
     def __init__(self, message: str, *, subcode: Optional[str] = None, details: Optional[Dict[str, Any]] = None):
         super().__init__(message, code="sql_parse_error", subcode=subcode, details=details, source="client")
@@ -113,27 +123,27 @@ class HttpError(DataverseError):
     Exception raised for HTTP request failures from the Dataverse Web API.
 
     :param message: Human-readable HTTP error message, typically from the API error response.
-    :type message: str
+    :type message: ``str``
     :param status_code: HTTP status code (e.g. 400, 404, 500).
-    :type status_code: int
+    :type status_code: ``int``
     :param is_transient: Whether the error is transient (429, 503, 504) and may succeed on retry.
-    :type is_transient: bool
+    :type is_transient: ``bool``
     :param subcode: Optional HTTP status category (e.g. ``"4xx"``, ``"5xx"``).
-    :type subcode: str or None
+    :type subcode: ``str`` | ``None``
     :param service_error_code: Optional Dataverse-specific error code from the API response.
-    :type service_error_code: str or None
+    :type service_error_code: ``str`` | ``None``
     :param correlation_id: Optional correlation ID for tracking requests across services.
-    :type correlation_id: str or None
+    :type correlation_id: ``str`` | ``None``
     :param request_id: Optional request ID from the API response headers.
-    :type request_id: str or None
+    :type request_id: ``str`` | ``None``
     :param traceparent: Optional W3C trace context for distributed tracing.
-    :type traceparent: str or None
+    :type traceparent: ``str`` | ``None``
     :param body_excerpt: Optional excerpt of the response body for diagnostics.
-    :type body_excerpt: str or None
+    :type body_excerpt: ``str`` | ``None``
     :param retry_after: Optional number of seconds to wait before retrying (from Retry-After header).
-    :type retry_after: int or None
+    :type retry_after: ``int`` | ``None``
     :param details: Optional additional diagnostic details.
-    :type details: dict or None
+    :type details: ``dict`` | ``None``
     """
     def __init__(
         self,

src/PowerPlatform/Dataverse/core/errors.py

@@ -4,9 +4,9 @@
 """
 HTTP client with automatic retry logic and timeout handling.
 
-This module provides :class:`HttpClient`, a wrapper around the requests library
-that adds configurable retry behavior for transient network errors and
-intelligent timeout management based on HTTP method types.
+This module provides :class:`~PowerPlatform.Dataverse.core.http.HttpClient`, a wrapper
+around the requests library that adds configurable retry behavior for transient
+network errors and intelligent timeout management based on HTTP method types.
 """
 
 from __future__ import annotations
@@ -25,16 +25,15 @@ class HttpClient:
     management for different HTTP methods.
     
     :param retries: Maximum number of retry attempts for transient errors. Default is 5.
-    :type retries: int or None
+    :type retries: ``int`` | ``None``
     :param backoff: Base delay in seconds between retry attempts. Default is 0.5.
-    :type backoff: float or None
+    :type backoff: ``float`` | ``None``
     :param timeout: Default request timeout in seconds. If None, uses per-method defaults.
-    :type timeout: float or None
+    :type timeout: ``float`` | ``None``
     """
 
     def __init__(
         self,
-        *,
         retries: Optional[int] = None,
         backoff: Optional[float] = None,
         timeout: Optional[float] = None,
@@ -51,12 +50,12 @@ def request(self, method: str, url: str, **kwargs: Any) -> requests.Response:
         and retries on network errors with exponential backoff.
         
         :param method: HTTP method (GET, POST, PUT, DELETE, etc.).
-        :type method: str
+        :type method: ``str``
         :param url: Target URL for the request.
-        :type url: str
+        :type url: ``str``
         :param kwargs: Additional arguments passed to ``requests.request()``, including headers, data, etc.
         :return: HTTP response object.
-        :rtype: requests.Response
+        :rtype: ``requests.Response``
         :raises requests.exceptions.RequestException: If all retry attempts fail.
         """
         # If no timeout is provided, use the user-specified default timeout if set;