sphinx doc string

Author: Max Wang

README.md

@@ -76,7 +76,7 @@ from azure.identity import (
     ClientCertificateCredential,
     AzureCliCredential
 )
-from PowerPlatform.Dataverse import DataverseClient
+from PowerPlatform.Dataverse.client import DataverseClient
 
 # Development options
 credential = InteractiveBrowserCredential()  # Browser authentication
@@ -111,7 +111,7 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 
 ```python
 from azure.identity import InteractiveBrowserCredential
-from PowerPlatform.Dataverse import DataverseClient
+from PowerPlatform.Dataverse.client import DataverseClient
 
 # Connect to Dataverse
 credential = InteractiveBrowserCredential()
@@ -285,7 +285,7 @@ For comprehensive information on Microsoft Dataverse and related technologies:
 The client raises structured exceptions for different error scenarios:
 
 ```python
-from PowerPlatform.Dataverse import DataverseClient
+from PowerPlatform.Dataverse.client import DataverseClient
 from PowerPlatform.Dataverse._core.errors import HttpError, ValidationError
 
 try:

examples/advanced/file_upload.py

@@ -24,7 +24,7 @@
 # Uncomment for local development from source
 # sys.path.append(str(Path(__file__).resolve().parents[2] / "src"))
 
-from PowerPlatform.Dataverse import DataverseClient
+from PowerPlatform.Dataverse.client import DataverseClient
 from azure.identity import InteractiveBrowserCredential  # type: ignore
 import requests
 

examples/basic/functional_testing.py

@@ -30,7 +30,7 @@
 from datetime import datetime
 
 # Import SDK components (assumes installation is already validated)
-from PowerPlatform.Dataverse import DataverseClient
+from PowerPlatform.Dataverse.client import DataverseClient
 from PowerPlatform.Dataverse._core.errors import HttpError, MetadataError
 from azure.identity import InteractiveBrowserCredential
 

examples/basic/installation_example.py

@@ -67,12 +67,13 @@ def validate_imports():
     print("-" * 50)
 
     try:
-        # Test main namespace import
-        from PowerPlatform.Dataverse import DataverseClient, __version__
+        # Test main namespace and client import
+        from PowerPlatform.Dataverse import __version__
+        from PowerPlatform.Dataverse.client import DataverseClient
 
-        print(f"  ✅ Main namespace: PowerPlatform.Dataverse")
+        print(f"  ✅ Namespace: PowerPlatform.Dataverse")
         print(f"  ✅ Package version: {__version__}")
-        print(f"  ✅ DataverseClient class: {DataverseClient}")
+        print(f"  ✅ Client class: PowerPlatform.Dataverse.client.DataverseClient")
 
         # Test submodule imports
         from PowerPlatform.Dataverse._core.errors import HttpError, MetadataError
@@ -176,7 +177,7 @@ def show_usage_examples():
         """
 🔧 Basic Setup:
 ```python
-from PowerPlatform.Dataverse import DataverseClient
+from PowerPlatform.Dataverse.client import DataverseClient
 from azure.identity import InteractiveBrowserCredential
 
 # Set up authentication
@@ -271,7 +272,7 @@ def interactive_test():
         return
 
     try:
-        from PowerPlatform.Dataverse import DataverseClient
+        from PowerPlatform.Dataverse.client import DataverseClient
         from azure.identity import InteractiveBrowserCredential
 
         print("  🔐 Setting up authentication...")

src/PowerPlatform/Dataverse/__init__.py

@@ -2,6 +2,5 @@
 # Licensed under the MIT license.
 
 from .__version__ import __version__
-from .client import DataverseClient
 
-__all__ = ["DataverseClient", "__version__"]
+__all__ = ["__version__"]

src/PowerPlatform/Dataverse/_core/auth.py

@@ -50,7 +50,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: :class:`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/config.py

@@ -21,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: :class:`int`
     :param http_retries: Optional maximum number of retry attempts for transient HTTP errors. Reserved for future use.
-    :type http_retries: ``int`` | ``None``
+    :type http_retries: :class:`int` or None
     :param http_backoff: Optional backoff multiplier (in seconds) between retry attempts. Reserved for future use.
-    :type http_backoff: ``float`` | ``None``
+    :type http_backoff: :class:`float` or None
     :param http_timeout: Optional request timeout in seconds. Reserved for future use.
-    :type http_timeout: ``float`` | ``None``
+    :type http_timeout: :class:`float` or None
     """
 
     language_code: int = 1033

src/PowerPlatform/Dataverse/_core/error_codes.py

@@ -82,9 +82,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: :class:`int`
     :return: Error subcode string (e.g., "http_400", "http_404").
-    :rtype: ``str``
+    :rtype: :class:`str`
     """
     return HTTP_STATUS_TO_SUBCODE.get(status, f"http_{status}")
 
@@ -97,8 +97,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: :class:`int`
     :return: True if the status code is considered transient.
-    :rtype: ``bool``
+    :rtype: :class:`bool`
     """
     return status in TRANSIENT_STATUS

src/PowerPlatform/Dataverse/_core/errors.py

@@ -22,19 +22,19 @@ class DataverseError(Exception):
     Base structured exception for the Dataverse SDK.
 
     :param message: Human-readable error message.
-    :type message: ``str``
+    :type message: :class:`str`
     :param code: Error category code (e.g. ``"validation_error"``, ``"http_error"``).
-    :type code: ``str``
+    :type code: :class:`str`
     :param subcode: Optional subcategory or specific error identifier.
-    :type subcode: ``str`` | ``None``
+    :type subcode: :class:`str` | None
     :param status_code: Optional HTTP status code if the error originated from an HTTP response.
-    :type status_code: ``int`` | ``None``
+    :type status_code: :class:`int` | None
     :param details: Optional dictionary containing additional diagnostic information.
-    :type details: ``dict`` | ``None``
+    :type details: :class:`dict` | None
     :param source: Error source, either ``"client"`` or ``"server"``.
-    :type source: ``str``
+    :type source: :class:`str`
     :param is_transient: Whether the error is potentially transient and may succeed on retry.
-    :type is_transient: ``bool``
+    :type is_transient: :class:`bool`
     """
 
     def __init__(
@@ -62,7 +62,7 @@ def to_dict(self) -> Dict[str, Any]:
         Convert the error to a dictionary representation.
 
         :return: Dictionary containing all error properties.
-        :rtype: ``dict``
+        :rtype: :class:`dict`
         """
         return {
             "message": self.message,
@@ -84,11 +84,11 @@ class ValidationError(DataverseError):
     Exception raised for client-side validation failures.
 
     :param message: Human-readable validation error message.
-    :type message: ``str``
+    :type message: :class:`str`
     :param subcode: Optional specific validation error identifier.
-    :type subcode: ``str`` | ``None``
+    :type subcode: :class:`str` | None
     :param details: Optional dictionary with additional validation context.
-    :type details: ``dict`` | ``None``
+    :type details: :class:`dict` | None
     """
 
     def __init__(self, message: str, *, subcode: Optional[str] = None, details: Optional[Dict[str, Any]] = None):
@@ -100,11 +100,11 @@ class MetadataError(DataverseError):
     Exception raised for metadata operation failures.
 
     :param message: Human-readable metadata error message.
-    :type message: ``str``
+    :type message: :class:`str`
     :param subcode: Optional specific metadata error identifier.
-    :type subcode: ``str`` | ``None``
+    :type subcode: :class:`str` | None
     :param details: Optional dictionary with additional metadata context.
-    :type details: ``dict`` | ``None``
+    :type details: :class:`dict` | None
     """
 
     def __init__(self, message: str, *, subcode: Optional[str] = None, details: Optional[Dict[str, Any]] = None):
@@ -116,11 +116,11 @@ class SQLParseError(DataverseError):
     Exception raised for SQL query parsing failures.
 
     :param message: Human-readable SQL parsing error message.
-    :type message: ``str``
+    :type message: :class:`str`
     :param subcode: Optional specific SQL parsing error identifier.
-    :type subcode: ``str`` | ``None``
+    :type subcode: :class:`str` | None
     :param details: Optional dictionary with SQL query context and parse information.
-    :type details: ``dict`` | ``None``
+    :type details: :class:`dict` | None
     """
 
     def __init__(self, message: str, *, subcode: Optional[str] = None, details: Optional[Dict[str, Any]] = None):
@@ -132,27 +132,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: :class:`str`
     :param status_code: HTTP status code (e.g. 400, 404, 500).
-    :type status_code: ``int``
+    :type status_code: :class:`int`
     :param is_transient: Whether the error is transient (429, 503, 504) and may succeed on retry.
-    :type is_transient: ``bool``
+    :type is_transient: :class:`bool`
     :param subcode: Optional HTTP status category (e.g. ``"4xx"``, ``"5xx"``).
-    :type subcode: ``str`` | ``None``
+    :type subcode: :class:`str` | None
     :param service_error_code: Optional Dataverse-specific error code from the API response.
-    :type service_error_code: ``str`` | ``None``
+    :type service_error_code: :class:`str` | None
     :param correlation_id: Optional correlation ID for tracking requests across services.
-    :type correlation_id: ``str`` | ``None``
+    :type correlation_id: :class:`str` | None
     :param request_id: Optional request ID from the API response headers.
-    :type request_id: ``str`` | ``None``
+    :type request_id: :class:`str` | None
     :param traceparent: Optional W3C trace context for distributed tracing.
-    :type traceparent: ``str`` | ``None``
+    :type traceparent: :class:`str` | None
     :param body_excerpt: Optional excerpt of the response body for diagnostics.
-    :type body_excerpt: ``str`` | ``None``
+    :type body_excerpt: :class:`str` | None
     :param retry_after: Optional number of seconds to wait before retrying (from Retry-After header).
-    :type retry_after: ``int`` | ``None``
+    :type retry_after: :class:`int` | None
     :param details: Optional additional diagnostic details.
-    :type details: ``dict`` | ``None``
+    :type details: :class:`dict` | None
     """
 
     def __init__(

src/PowerPlatform/Dataverse/_core/http.py

@@ -25,11 +25,11 @@ class HttpClient:
     management for different HTTP methods.
 
     :param retries: Maximum number of retry attempts for transient errors. Default is 5.
-    :type retries: ``int`` | ``None``
+    :type retries: :class:`int` | None
     :param backoff: Base delay in seconds between retry attempts. Default is 0.5.
-    :type backoff: ``float`` | ``None``
+    :type backoff: :class:`float` | None
     :param timeout: Default request timeout in seconds. If None, uses per-method defaults.
-    :type timeout: ``float`` | ``None``
+    :type timeout: :class:`float` | None
     """
 
     def __init__(
@@ -50,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: :class:`str`
         :param url: Target URL for the request.
-        :type url: ``str``
+        :type url: :class:`str`
         :param kwargs: Additional arguments passed to ``requests.request()``, including headers, data, etc.
         :return: HTTP response object.
-        :rtype: ``requests.Response``
+        :rtype: :class:`requests.Response`
         :raises requests.exceptions.RequestException: If all retry attempts fail.
         """
         # If no timeout is provided, use the user-specified default timeout if set;