refactor: complete SDK architecture and quality improvements

Major improvements for PyPI readiness:

Architecture & Standards:
- Align with Microsoft Azure SDK patterns (explicit imports only)
- Remove re-exports from all submodule __init__.py files
- Fix py2docfx documentation duplication issues
- Clean up verbose docstring additions for professional appearance

Code Quality:
- Fix deprecated datetime.utcnow() → datetime.now(timezone.utc)
- Update explicit imports: error_codes module usage consistency
- Eliminate all test warnings (pytest collection + deprecation)
- Rename test helper classes: TestClient→MockClient, TestableClient→MockableClient

Import Consistency:
- Replace 'from core import error_codes as ec' with direct imports
- Use explicit imports throughout codebase for better maintainability
- All HTTP error constants and functions imported directly

Result: Zero warnings, Microsoft-compliant architecture, PyPI-ready SDK
All tests pass, no breaking changes, professional documentation structure

Author: suyask-msft

src/PowerPlatform/Dataverse/core/__init__.py

@@ -6,13 +6,6 @@
 
 This module contains the foundational components including authentication,
 configuration, HTTP client, and error handling.
-
-Import classes directly from their specific modules:
-    - Authentication: from .auth import AuthManager, TokenPair
-    - Configuration: from .config import DataverseConfig  
-    - Errors: from .errors import DataverseError, HttpError, etc.
-    - HTTP Client: from .http import HttpClient
 """
 
-# No re-exports to avoid documentation duplication with py2docfx
 __all__ = []

src/PowerPlatform/Dataverse/core/errors.py

@@ -53,7 +53,7 @@ def __init__(
         self.details = details or {}
         self.source = source or "client"
         self.is_transient = is_transient
-        self.timestamp = _dt.datetime.utcnow().isoformat() + "Z"
+        self.timestamp = _dt.datetime.now(_dt.timezone.utc).isoformat().replace('+00:00', 'Z')
 
     def to_dict(self) -> Dict[str, Any]:
         """

src/PowerPlatform/Dataverse/data/__init__.py

@@ -6,11 +6,6 @@
 
 This module contains OData protocol handling, CRUD operations, metadata management,
 SQL query functionality, and file upload capabilities.
-
-Import classes directly from their specific modules:
-    - OData operations: from .odata import ODataClient
-    - File uploads: from .upload import ODataFileUpload
 """
 
-# No re-exports to avoid documentation duplication with py2docfx
 __all__ = []

src/PowerPlatform/Dataverse/data/odata.py

@@ -17,7 +17,18 @@
 from ..core.http import HttpClient
 from .upload import ODataFileUpload
 from ..core.errors import *
-from ..core import error_codes as ec
+from ..core.error_codes import (
+    http_subcode, 
+    is_transient_status,
+    VALIDATION_SQL_NOT_STRING,
+    VALIDATION_SQL_EMPTY,
+    METADATA_ENTITYSET_NOT_FOUND,
+    METADATA_ENTITYSET_NAME_MISSING,
+    METADATA_TABLE_NOT_FOUND,
+    METADATA_TABLE_ALREADY_EXISTS,
+    METADATA_COLUMN_NOT_FOUND,
+    VALIDATION_UNSUPPORTED_CACHE_KIND,
+)
 
 from ..__version__ import __version__ as _SDK_VERSION
 
@@ -121,7 +132,7 @@ def _request(self, method: str, url: str, *, expected: tuple[int, ...] = (200, 2
         except Exception:
             pass
         sc = r.status_code
-        subcode = ec.http_subcode(sc)
+        subcode = http_subcode(sc)
         correlation_id = headers.get("x-ms-correlation-request-id") or headers.get("x-ms-correlation-id")
         request_id = headers.get("x-ms-client-request-id") or headers.get("request-id") or headers.get("x-ms-request-id")
         traceparent = headers.get("traceparent")
@@ -132,7 +143,7 @@ def _request(self, method: str, url: str, *, expected: tuple[int, ...] = (200, 2
                 retry_after = int(ra)
             except Exception:
                 retry_after = None
-        is_transient = ec.is_transient_status(sc)
+        is_transient = is_transient_status(sc)
         raise HttpError(
             msg,
             status_code=sc,
@@ -558,9 +569,9 @@ def _query_sql(self, sql: str) -> list[dict[str, Any]]:
            Endpoint form: ``GET /{entity_set}?sql=<encoded select>``. The client extracts the logical table name, resolves the entity set (metadata cached), then issues the request. Only a constrained SELECT subset is supported by the platform.
         """
         if not isinstance(sql, str):
-            raise ValidationError("sql must be a string", subcode=ec.VALIDATION_SQL_NOT_STRING)
+            raise ValidationError("sql must be a string", subcode=VALIDATION_SQL_NOT_STRING)
         if not sql.strip():
-            raise ValidationError("sql must be a non-empty string", subcode=ec.VALIDATION_SQL_EMPTY)
+            raise ValidationError("sql must be a non-empty string", subcode=VALIDATION_SQL_EMPTY)
         sql = sql.strip()
 
         # Extract logical table name via helper (robust to identifiers ending with 'from')
@@ -631,14 +642,14 @@ def _entity_set_from_logical(self, logical: str) -> str:
             plural_hint = " (did you pass a plural entity set name instead of the singular logical name?)" if logical.endswith("s") and not logical.endswith("ss") else ""
             raise MetadataError(
                 f"Unable to resolve entity set for logical name '{logical}'. Provide the singular logical name.{plural_hint}",
-                subcode=ec.METADATA_ENTITYSET_NOT_FOUND,
+                subcode=METADATA_ENTITYSET_NOT_FOUND,
             )
         md = items[0]
         es = md.get("EntitySetName")
         if not es:
             raise MetadataError(
                 f"Metadata response missing EntitySetName for logical '{logical}'.",
-                subcode=ec.METADATA_ENTITYSET_NAME_MISSING,
+                subcode=METADATA_ENTITYSET_NAME_MISSING,
             )
         self._logical_to_entityset_cache[logical] = es
         primary_id_attr = md.get("PrimaryIdAttribute")
@@ -1150,7 +1161,7 @@ def _delete_table(self, tablename: str) -> None:
         if not ent or not ent.get("MetadataId"):
             raise MetadataError(
                 f"Table '{entity_schema}' not found.",
-                subcode=ec.METADATA_TABLE_NOT_FOUND,
+                subcode=METADATA_TABLE_NOT_FOUND,
             )
         metadata_id = ent["MetadataId"]
         url = f"{self.api}/EntityDefinitions({metadata_id})"
@@ -1191,7 +1202,7 @@ def _create_table(
         if ent:
             raise MetadataError(
                 f"Table '{entity_schema}' already exists.",
-                subcode=ec.METADATA_TABLE_ALREADY_EXISTS,
+                subcode=METADATA_TABLE_ALREADY_EXISTS,
             )
 
         created_cols: List[str] = []
@@ -1254,7 +1265,7 @@ def _create_columns(
         if not ent or not ent.get("MetadataId"):
             raise MetadataError(
                 f"Table '{entity_schema}' not found.",
-                subcode=ec.METADATA_TABLE_NOT_FOUND,
+                subcode=METADATA_TABLE_NOT_FOUND,
             )
 
         metadata_id = ent.get("MetadataId")
@@ -1317,7 +1328,7 @@ def _delete_columns(
         if not ent or not ent.get("MetadataId"):
             raise MetadataError(
                 f"Table '{entity_schema}' not found.",
-                subcode=ec.METADATA_TABLE_NOT_FOUND,
+                subcode=METADATA_TABLE_NOT_FOUND,
             )
 
         metadata_id = ent.get("MetadataId")
@@ -1330,7 +1341,7 @@ def _delete_columns(
             if not attr_meta:
                 raise MetadataError(
                     f"Column '{schema_name}' not found on table '{entity_schema}'.",
-                    subcode=ec.METADATA_COLUMN_NOT_FOUND,
+                    subcode=METADATA_COLUMN_NOT_FOUND,
                 )
 
             attr_metadata_id = attr_meta.get("MetadataId")
@@ -1372,7 +1383,7 @@ def _flush_cache(
         if k != "picklist":
             raise ValidationError(
                 f"Unsupported cache kind '{kind}' (only 'picklist' is implemented)",
-                subcode=ec.VALIDATION_UNSUPPORTED_CACHE_KIND,
+                subcode=VALIDATION_UNSUPPORTED_CACHE_KIND,
             )
 
         removed = len(self._picklist_label_cache)

src/PowerPlatform/Dataverse/utils/__init__.py

@@ -5,10 +5,6 @@
 Utilities and adapters for the Dataverse SDK.
 
 This module contains adapters (like Pandas integration).
-
-Import classes directly from their specific modules:
-    - Pandas integration: from .pandas_adapter import PandasODataClient
 """
 
-# No re-exports to avoid documentation duplication with py2docfx
 __all__ = []

tests/unit/core/test_http_errors.py

@@ -3,7 +3,7 @@
 
 import pytest
 from PowerPlatform.Dataverse.core.errors import HttpError
-from PowerPlatform.Dataverse.core import error_codes as ec
+from PowerPlatform.Dataverse.core.error_codes import HTTP_404, HTTP_429, HTTP_500
 from PowerPlatform.Dataverse.data.odata import ODataClient
 
 class DummyAuth:
@@ -34,7 +34,7 @@ def json_fail(): raise ValueError("non-json")
             r.json = json_fail
         return r
 
-class TestClient(ODataClient):
+class MockClient(ODataClient):
     def __init__(self, responses):
         super().__init__(DummyAuth(), "https://org.example", None)
         self._http = DummyHTTP(responses)
@@ -47,11 +47,11 @@ def test_http_404_subcode_and_service_code():
         {"x-ms-correlation-request-id": "cid1"},
         {"error": {"code": "0x800404", "message": "Not found"}},
     )]
-    c = TestClient(responses)
+    c = MockClient(responses)
     with pytest.raises(HttpError) as ei:
         c._request("get", c.api + "/accounts(abc)")
     err = ei.value.to_dict()
-    assert err["subcode"] == ec.HTTP_404
+    assert err["subcode"] == HTTP_404
     assert err["details"]["service_error_code"] == "0x800404"
 
 
@@ -61,12 +61,12 @@ def test_http_429_transient_and_retry_after():
         {"Retry-After": "7"},
         {"error": {"message": "Throttle"}},
     )]
-    c = TestClient(responses)
+    c = MockClient(responses)
     with pytest.raises(HttpError) as ei:
         c._request("get", c.api + "/accounts")
     err = ei.value.to_dict()
     assert err["is_transient"] is True
-    assert err["subcode"] == ec.HTTP_429
+    assert err["subcode"] == HTTP_429
     assert err["details"]["retry_after"] == 7
 
 
@@ -76,11 +76,11 @@ def test_http_500_body_excerpt():
         {},
         "Internal failure XYZ stack truncated",
     )]
-    c = TestClient(responses)
+    c = MockClient(responses)
     with pytest.raises(HttpError) as ei:
         c._request("get", c.api + "/accounts")
     err = ei.value.to_dict()
-    assert err["subcode"] == ec.HTTP_500
+    assert err["subcode"] == HTTP_500
     assert "XYZ stack" in err["details"]["body_excerpt"]
 
 
@@ -90,7 +90,7 @@ def test_http_non_mapped_status_code_subcode_fallback():
         {},
         {"error": {"message": "Teapot"}},
     )]
-    c = TestClient(responses)
+    c = MockClient(responses)
     with pytest.raises(HttpError) as ei:
         c._request("get", c.api + "/accounts")
     err = ei.value.to_dict()

tests/unit/data/test_logical_crud.py

@@ -34,7 +34,7 @@ def json_func():
         resp.json = json_func
         return resp
 
-class TestableClient(ODataClient):
+class MockableClient(ODataClient):
     def __init__(self, responses):
         super().__init__(DummyAuth(), "https://org.example", None)
         self._http = DummyHTTPClient(responses)
@@ -76,7 +76,7 @@ def test_single_create_update_delete_get():
         (204, {}, {}),  # update (no body)
         (204, {}, {}),  # delete
     ]
-    c = TestableClient(responses)
+    c = MockableClient(responses)
     entity_set = c._entity_set_from_logical("account")
     rid = c._create(entity_set, "account", {"name": "Acme"})
     assert rid == guid
@@ -96,7 +96,7 @@ def test_bulk_create_and_update():
         (204, {}, {}),  # UpdateMultiple broadcast
         (204, {}, {}),  # UpdateMultiple 1:1
     ]
-    c = TestableClient(responses)
+    c = MockableClient(responses)
     entity_set = c._entity_set_from_logical("account")
     ids = c._create_multiple(entity_set, "account", [{"name": "A"}, {"name": "B"}])
     assert ids == [g1, g2]
@@ -111,7 +111,7 @@ def test_get_multiple_paging():
         (200, {}, {"value": [{"accountid": "1"}], "@odata.nextLink": "https://org.example/api/data/v9.2/accounts?$skip=1"}),
         (200, {}, {"value": [{"accountid": "2"}]}),
     ]
-    c = TestableClient(responses)
+    c = MockableClient(responses)
     pages = list(c._get_multiple("account", select=["accountid"], page_size=1))
     assert pages == [[{"accountid": "1"}], [{"accountid": "2"}]]
 
@@ -120,6 +120,6 @@ def test_unknown_logical_name_raises():
     responses = [
         (200, {}, {"value": []}),  # metadata lookup returns empty
     ]
-    c = TestableClient(responses)
+    c = MockableClient(responses)
     with pytest.raises(MetadataError):
         c._entity_set_from_logical("nonexistent")