redblack-python-sdk 0.1.0__py3-none-any.whl

redblack/models/base.py

@@ -0,0 +1,150 @@
+"""Shared behavior for generated RedBlack wire models.
+
+This module is hand maintained.  The concrete models in :mod:`generated` are
+created from the captured API contract.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from datetime import datetime
+from enum import IntEnum
+from typing import Any, Self
+
+from pydantic import BaseModel, ConfigDict, PrivateAttr, model_validator
+
+from ..response import HttpMetadata
+
+
+class UnsetType:
+    """Marker used when an optional request field was not supplied.
+
+    ``None`` is a real JSON value.  A separate marker lets PATCH and other
+    request models distinguish an omitted field from an explicitly-null field.
+    """
+
+    __slots__ = ()
+
+    def __copy__(self) -> UnsetType:
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> UnsetType:
+        del memo
+        return self
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+UNSET = UnsetType()
+
+
+def _walk_values(value: Any) -> Iterator[Any]:
+    """Yield values nested in supported request containers."""
+
+    yield value
+    if isinstance(value, BaseModel):
+        for field_name in value.model_fields_set:
+            yield from _walk_values(getattr(value, field_name))
+    elif isinstance(value, dict):
+        for child in value.values():
+            yield from _walk_values(child)
+    elif isinstance(value, list | tuple | set | frozenset):
+        for child in value:
+            yield from _walk_values(child)
+
+
+class RequestModel(BaseModel):
+    """Base for outbound bodies.
+
+    Request models reject unknown keys and accept either Python field names or
+    their exact wire aliases.  Datetimes must carry a timezone so local wall
+    time can never be sent accidentally.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="forbid",
+        hide_input_in_errors=True,
+        populate_by_name=True,
+        protected_namespaces=(),
+    )
+
+    @model_validator(mode="after")
+    def _reject_naive_datetimes(self) -> Self:
+        for value in _walk_values(self):
+            if isinstance(value, datetime) and (value.tzinfo is None or value.utcoffset() is None):
+                raise ValueError("request datetimes must include an explicit UTC offset")
+        return self
+
+
+class ResponseModel(BaseModel):
+    """Base for inbound bodies.
+
+    Response models preserve unknown properties because RedBlack documents
+    additive response fields as a non-breaking API change.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="allow",
+        hide_input_in_errors=True,
+        populate_by_name=True,
+        protected_namespaces=(),
+    )
+
+    _http: HttpMetadata | None = PrivateAttr(default=None)
+
+    @property
+    def http(self) -> HttpMetadata | None:
+        """Non-wire HTTP metadata attached by the client, if available."""
+
+        return self._http
+
+    def _attach_http(self, metadata: HttpMetadata) -> Self:
+        """Attach transport metadata without adding it to model serialization."""
+
+        self._http = metadata
+        return self
+
+
+class ODataPageModel(ResponseModel):
+    """Common conveniences for generated OData collection envelopes."""
+
+    @property
+    def items(self) -> list[Any]:
+        value = getattr(self, "value", None)
+        return value if isinstance(value, list) else []
+
+    @property
+    def total_count(self) -> int | None:
+        value = getattr(self, "odata_count", None)
+        return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+class OpenIntEnum(IntEnum):
+    """Integer enum that retains response values added by a newer API."""
+
+    @classmethod
+    def _missing_(cls, value: object) -> OpenIntEnum | None:
+        if not isinstance(value, int) or isinstance(value, bool):
+            return None
+
+        # Enum's supported extension hook is `_missing_`.  Creating a
+        # pseudo-member retains the integer and keeps future values comparable
+        # without pretending that the SDK knows their vendor name.
+        pseudo_member = int.__new__(cls, value)
+        pseudo_member._name_ = f"UNKNOWN_{value}".replace("-", "NEG_")
+        pseudo_member._value_ = value
+        cls._value2member_map_[value] = pseudo_member
+        return pseudo_member
+
+
+__all__ = [
+    "OpenIntEnum",
+    "ODataPageModel",
+    "RequestModel",
+    "ResponseModel",
+    "UNSET",
+    "UnsetType",
+]