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

redblack/resources/_base.py

@@ -0,0 +1,212 @@
+"""Shared protocols and mechanics for hand-written resource facades."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, is_dataclass
+from typing import Any, Generic, Literal, Protocol, TypeAlias, TypeVar, cast, runtime_checkable
+
+from ..odata import ODataQuery
+from ..pagination import Page
+from ..response import ApiResponse, HttpMetadata
+
+T = TypeVar("T")
+HttpInfoMode = TypeVar("HttpInfoMode", Literal[False], Literal[True])
+ApiResponseProtocol: TypeAlias = ApiResponse[T]
+HttpMetadataProtocol: TypeAlias = HttpMetadata
+
+
+@runtime_checkable
+class ClientProtocol(Protocol):
+    """The narrow client interface consumed by every resource group."""
+
+    def request(
+        self,
+        operation_id: str,
+        *,
+        path_params: Mapping[str, object] | None = None,
+        query: Mapping[str, object] | None = None,
+        headers: Mapping[str, str] | None = None,
+        json: object | None = None,
+        stream: bool = False,
+        timeout_budget: float | None = None,
+    ) -> ApiResponse[Any]: ...
+
+
+def read_member(value: object, *names: str) -> Any:
+    if isinstance(value, Mapping):
+        for name in names:
+            if name in value:
+                return value[name]
+        return None
+    for name in names:
+        if hasattr(value, name):
+            return getattr(value, name)
+    return None
+
+
+def enum_value(value: object, *field_names: str) -> int | None:
+    wrapper = read_member(value, *field_names)
+    raw = read_member(wrapper, "value") if wrapper is not None else None
+    if raw is None and isinstance(wrapper, int) and not isinstance(wrapper, bool):
+        raw = wrapper
+    if isinstance(raw, bool) or not isinstance(raw, int):
+        return None
+    return raw
+
+
+def response_header(response: ApiResponse[Any], name: str) -> str | None:
+    if name.casefold() == "location":
+        location = getattr(response, "location", None)
+        if location:
+            return str(location)
+        location = getattr(response.http, "location", None)
+        if location:
+            return str(location)
+    if name.casefold() == "etag":
+        etag = getattr(response.http, "etag", None)
+        if etag:
+            return str(etag)
+    target = name.casefold()
+    for key, value in response.headers.items():
+        if key.casefold() == target:
+            return value
+    for key, value in response.http.headers.items():
+        if key.casefold() == target:
+            return value
+    return None
+
+
+def body_mapping(value: object) -> dict[str, Any]:
+    """Convert a request model or mapping when a facade must add safe fields."""
+
+    if isinstance(value, Mapping):
+        return dict(value)
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return dict(
+            cast(Mapping[str, Any], model_dump(by_alias=True, exclude_unset=True, mode="python"))
+        )
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    raise TypeError("request value must be a mapping, dataclass, or Pydantic model")
+
+
+def body_value(value: object) -> object:
+    """Serialize nested request models without losing omitted/null semantics."""
+
+    if isinstance(value, Mapping):
+        return {key: body_value(item) for key, item in value.items()}
+    if isinstance(value, list | tuple):
+        return [body_value(item) for item in value]
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return model_dump(by_alias=True, exclude_unset=True, mode="python")
+    if is_dataclass(value) and not isinstance(value, type):
+        return {key: body_value(item) for key, item in asdict(value).items()}
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class VersionedResource(Generic[T]):
+    """A resource value paired with the exact server ETag used for writes."""
+
+    data: T
+    etag: str | None
+    http: HttpMetadataProtocol
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.data, name)
+
+    def __getitem__(self, key: object) -> Any:
+        return self.data[key]  # type: ignore[index]
+
+
+class Resource(Generic[HttpInfoMode]):
+    OPERATION_IDS: frozenset[str] = frozenset()
+
+    def __init__(self, client: ClientProtocol, *, with_http_info: bool = False) -> None:
+        self._client = client
+        self._with_http_info = with_http_info
+
+    def _request(
+        self,
+        operation_id: str,
+        *,
+        path_params: Mapping[str, object] | None = None,
+        query: Mapping[str, object] | None = None,
+        headers: Mapping[str, str] | None = None,
+        json: object | None = None,
+        stream: bool = False,
+        timeout_budget: float | None = None,
+    ) -> ApiResponse[Any]:
+        if timeout_budget is None:
+            return self._client.request(
+                operation_id,
+                path_params=path_params,
+                query=query,
+                headers=headers,
+                json=json,
+                stream=stream,
+            )
+        return self._client.request(
+            operation_id,
+            path_params=path_params,
+            query=query,
+            headers=headers,
+            json=json,
+            stream=stream,
+            timeout_budget=timeout_budget,
+        )
+
+    def _page(
+        self,
+        operation_id: str,
+        *,
+        odata: ODataQuery,
+        path_params: Mapping[str, object] | None = None,
+        extra_query: Mapping[str, object] | None = None,
+    ) -> Page[Any] | ApiResponse[Page[Any]]:
+        response = self._request(
+            operation_id,
+            path_params=path_params,
+            query={**odata.to_params(), **(extra_query or {})},
+        )
+        page = Page.from_data(response.data, query=odata, http=response.http)
+        return self._finish(response, page)
+
+    def _page_value(
+        self,
+        operation_id: str,
+        *,
+        odata: ODataQuery,
+        path_params: Mapping[str, object] | None = None,
+        extra_query: Mapping[str, object] | None = None,
+    ) -> Page[Any]:
+        """Return an internal page regardless of the public response view."""
+
+        response = self._request(
+            operation_id,
+            path_params=path_params,
+            query={**odata.to_params(), **(extra_query or {})},
+        )
+        return Page.from_data(response.data, query=odata, http=response.http)
+
+    def _finish(self, response: ApiResponse[Any], value: T) -> T | ApiResponse[T]:
+        if self._with_http_info:
+            return response.with_data(value)
+        return value
+
+
+def require_positive_identifier(name: str, value: int) -> None:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{name} must be an integer")
+    if value <= 0:
+        raise ValueError(f"{name} must be greater than zero")
+
+
+def require_etag(if_match: str) -> None:
+    if not isinstance(if_match, str):
+        raise TypeError("if_match must be a string")
+    if not if_match.strip():
+        raise ValueError("if_match must not be empty")

redblack/resources/_collections.py

@@ -0,0 +1,80 @@
+"""Reusable collection method implementation."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+from ..odata import DEFAULT_PAGE_SIZE, ODataQuery
+from ..pagination import Page, Paginator
+from ._base import ApiResponseProtocol, HttpInfoMode, Resource
+
+
+class CollectionResource(Resource[HttpInfoMode]):
+    LIST_OPERATION_ID: str
+
+    def _list(
+        self,
+        *,
+        filter: str | None = None,
+        order_by: str | None = None,
+        top: int | None = None,
+        skip: int | None = None,
+        count: bool | None = None,
+        path_params: Mapping[str, object] | None = None,
+        extra_query: Mapping[str, object] | None = None,
+    ) -> Page[Any] | ApiResponseProtocol[Page[Any]]:
+        query = ODataQuery(filter=filter, order_by=order_by, top=top, skip=skip, count=count)
+        return self._page(
+            self.LIST_OPERATION_ID, odata=query, path_params=path_params, extra_query=extra_query
+        )
+
+    def _iter_pages(
+        self,
+        *,
+        filter: str | None = None,
+        order_by: str | None = None,
+        count: bool | None = None,
+        start_skip: int = 0,
+        page_size: int = DEFAULT_PAGE_SIZE,
+        max_items: int | None = None,
+        path_params: Mapping[str, object] | None = None,
+        extra_query: Mapping[str, object] | None = None,
+    ) -> Iterator[Page[Any]]:
+        base = ODataQuery(filter=filter, order_by=order_by, skip=start_skip, count=count)
+        paginator = Paginator(
+            fetch_page=lambda query: self._page_value(
+                self.LIST_OPERATION_ID,
+                odata=query,
+                path_params=path_params,
+                extra_query=extra_query,
+            ),
+            query=base,
+            page_size=page_size,
+            max_items=max_items,
+        )
+        return paginator.iter_pages()
+
+    def _iter_all(
+        self,
+        *,
+        filter: str | None = None,
+        order_by: str | None = None,
+        count: bool | None = None,
+        start_skip: int = 0,
+        page_size: int = DEFAULT_PAGE_SIZE,
+        max_items: int | None = None,
+        path_params: Mapping[str, object] | None = None,
+        extra_query: Mapping[str, object] | None = None,
+    ) -> Iterator[Any]:
+        pages = self._iter_pages(
+            filter=filter,
+            order_by=order_by,
+            count=count,
+            start_skip=start_skip,
+            page_size=page_size,
+            max_items=max_items,
+            path_params=path_params,
+            extra_query=extra_query,
+        )
+        return (item for page in pages for item in page.items)

redblack/resources/_exports.py

@@ -0,0 +1,215 @@
+"""Shared implementation for the four documented export operation families."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from os import PathLike
+from threading import Event
+from typing import Any, Generic, TypeVar
+
+from ..downloads import (
+    AddressResolver,
+    Downloader,
+    DownloadResult,
+    StorageUrlPolicy,
+    validate_storage_url,
+)
+from ..errors import RedBlackError
+from ..polling import Poller, PollOutcome
+from ._base import (
+    ApiResponseProtocol,
+    ClientProtocol,
+    HttpInfoMode,
+    Resource,
+    enum_value,
+    read_member,
+    require_positive_identifier,
+    response_header,
+)
+
+T = TypeVar("T")
+
+
+class WorkflowProtocolError(RedBlackError):
+    """A successful workflow response omitted data required by its contract."""
+
+
+@dataclass(frozen=True, slots=True)
+class ExportOperations:
+    create: str
+    status: str
+    file: str
+    body_required: bool
+
+
+def _parse_datetime(value: object) -> datetime | None:
+    if isinstance(value, datetime):
+        return value
+    if not isinstance(value, str) or not value:
+        return None
+    normalized = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        return datetime.fromisoformat(normalized)
+    except ValueError:
+        return None
+
+
+@dataclass(slots=True)
+class ExportJobHandle(Generic[T]):
+    """A client-bound handle for one RedBlack export job."""
+
+    _client: ClientProtocol
+    job_id: int
+    _operations: ExportOperations
+    latest: T | None = None
+
+    def __post_init__(self) -> None:
+        require_positive_identifier("job_id", self.job_id)
+
+    def _refresh_with_timeout(self, timeout_budget: float | None) -> T:
+        if timeout_budget is None:
+            return self.refresh()
+        response = self._client.request(
+            self._operations.status,
+            path_params={"jobId": self.job_id},
+            timeout_budget=timeout_budget,
+        )
+        self.latest = response.data
+        return response.data
+
+    def refresh(self) -> T:
+        response = self._client.request(self._operations.status, path_params={"jobId": self.job_id})
+        self.latest = response.data
+        return response.data
+
+    status = refresh
+
+    @staticmethod
+    def _classify(value: object) -> PollOutcome:
+        status = enum_value(value, "job_status", "jobStatus", "export_status", "exportStatus")
+        if status == 3:
+            return PollOutcome.SUCCEEDED
+        if status in {4, 5}:
+            return PollOutcome.FAILED
+        return PollOutcome.PENDING
+
+    @staticmethod
+    def _suggested_delay(value: object) -> float | None:
+        target = _parse_datetime(
+            read_member(value, "suggested_next_poll_time", "suggestedNextPollTime")
+        )
+        if target is None:
+            return None
+        if target.tzinfo is None:
+            target = target.replace(tzinfo=UTC)
+        return max(0.0, (target - datetime.now(UTC)).total_seconds())
+
+    def wait(
+        self,
+        *,
+        timeout: float | None = 300.0,
+        poll_interval: float = 1.0,
+        max_interval: float = 30.0,
+        backoff_factor: float = 1.5,
+        stop_event: Event | None = None,
+        raise_on_failure: bool = True,
+    ) -> T:
+        return Poller(
+            refresh=self.refresh,
+            classify=self._classify,
+            suggested_delay=self._suggested_delay,
+            refresh_with_timeout=self._refresh_with_timeout,
+        ).wait(
+            timeout=timeout,
+            poll_interval=poll_interval,
+            max_interval=max_interval,
+            backoff_factor=backoff_factor,
+            stop_event=stop_event,
+            raise_on_failure=raise_on_failure,
+        )
+
+    def file_response(self) -> ApiResponseProtocol[None]:
+        """Request the RedBlack file endpoint without following its redirect."""
+
+        return self._client.request(
+            self._operations.file,
+            path_params={"jobId": self.job_id},
+            stream=True,
+        )
+
+    def download_url(
+        self,
+        *,
+        policy: StorageUrlPolicy | None = None,
+        resolver: AddressResolver | None = None,
+    ) -> str:
+        """Obtain and validate the five-minute storage URL."""
+
+        response = self.file_response()
+        location = response_header(response, "Location")
+        if not location:
+            raise WorkflowProtocolError("export file response omitted Location")
+        return validate_storage_url(location, policy=policy, resolver=resolver)
+
+    def download_to(
+        self,
+        destination: str | PathLike[str],
+        *,
+        overwrite: bool = False,
+        policy: StorageUrlPolicy | None = None,
+        download_client: object | None = None,
+        resolver: AddressResolver | None = None,
+    ) -> DownloadResult:
+        """Download with a credential-free client and atomic file publication."""
+
+        active_policy = policy or StorageUrlPolicy()
+        url = self.download_url(policy=active_policy, resolver=resolver)
+        downloader = Downloader(policy=active_policy, client=download_client, resolver=resolver)
+        return downloader.download_to(url, destination, overwrite=overwrite)
+
+    @property
+    def has_failures(self) -> bool:
+        if self.latest is None:
+            return False
+        fault_reason = read_member(self.latest, "fault_reason", "faultReason")
+        return bool(fault_reason) or self._classify(self.latest) is PollOutcome.FAILED
+
+
+class ExportResource(Resource[HttpInfoMode]):
+    EXPORT_OPERATIONS: ExportOperations
+
+    def _create_export(
+        self, *, filter: str | None = None
+    ) -> ExportJobHandle[Any] | ApiResponseProtocol[ExportJobHandle[Any]]:
+        if filter is not None:
+            if not isinstance(filter, str):
+                raise TypeError("filter must be a string")
+            if not filter.strip():
+                raise ValueError("filter must not be empty")
+            body: object | None = {"filter": filter}
+        elif self.EXPORT_OPERATIONS.body_required:
+            # Restriction/equivalent requestBody is required even though its
+            # only property is optional.
+            body = {}
+        else:
+            body = None
+        response = self._request(self.EXPORT_OPERATIONS.create, json=body)
+        job_id = read_member(response.data, "id")
+        if isinstance(job_id, bool) or not isinstance(job_id, int):
+            raise WorkflowProtocolError("export create response omitted integer id")
+        handle = ExportJobHandle(
+            self._client,
+            job_id,
+            self.EXPORT_OPERATIONS,
+            latest=response.data,
+        )
+        return self._finish(response, handle)
+
+    def _get_export(
+        self, job_id: int
+    ) -> ExportJobHandle[Any] | ApiResponseProtocol[ExportJobHandle[Any]]:
+        require_positive_identifier("job_id", job_id)
+        response = self._request(self.EXPORT_OPERATIONS.status, path_params={"jobId": job_id})
+        handle = ExportJobHandle(self._client, job_id, self.EXPORT_OPERATIONS, latest=response.data)
+        return self._finish(response, handle)

redblack/resources/accounts.py

@@ -0,0 +1,132 @@
+"""Accounts resource operations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Literal, overload
+
+from ..models import Account, AccountExportJob
+from ..odata import DEFAULT_PAGE_SIZE
+from ..pagination import Page
+from ._base import ApiResponseProtocol, HttpInfoMode
+from ._collections import CollectionResource
+from ._exports import ExportJobHandle, ExportOperations, ExportResource
+
+
+class AccountsResource(CollectionResource[HttpInfoMode], ExportResource[HttpInfoMode]):
+    LIST_OPERATION_ID = "Accounts_QueryAccounts"
+    EXPORT_OPERATIONS = ExportOperations(
+        create="Accounts_Export",
+        status="Accounts_GetBulkExportSessionStatus",
+        file="Accounts_GetBulkExportFile",
+        body_required=False,
+    )
+    OPERATION_IDS = frozenset(
+        {
+            LIST_OPERATION_ID,
+            EXPORT_OPERATIONS.create,
+            EXPORT_OPERATIONS.status,
+            EXPORT_OPERATIONS.file,
+        }
+    )
+
+    @overload
+    def list(
+        self: AccountsResource[Literal[False]],
+        *,
+        filter: str | None = None,
+        order_by: str | None = None,
+        top: int | None = None,
+        skip: int | None = None,
+        count: bool | None = None,
+    ) -> Page[Account]: ...
+
+    @overload
+    def list(
+        self: AccountsResource[Literal[True]],
+        *,
+        filter: str | None = None,
+        order_by: str | None = None,
+        top: int | None = None,
+        skip: int | None = None,
+        count: bool | None = None,
+    ) -> ApiResponseProtocol[Page[Account]]: ...
+
+    def list(
+        self,
+        *,
+        filter: str | None = None,
+        order_by: str | None = None,
+        top: int | None = None,
+        skip: int | None = None,
+        count: bool | None = None,
+    ) -> Page[Account] | ApiResponseProtocol[Page[Account]]:
+        return self._list(filter=filter, order_by=order_by, top=top, skip=skip, count=count)
+
+    def iter_pages(
+        self,
+        *,
+        filter: str | None = None,
+        order_by: str | None = None,
+        count: bool | None = None,
+        start_skip: int = 0,
+        page_size: int = DEFAULT_PAGE_SIZE,
+        max_items: int | None = None,
+    ) -> Iterator[Page[Account]]:
+        return self._iter_pages(
+            filter=filter,
+            order_by=order_by,
+            count=count,
+            start_skip=start_skip,
+            page_size=page_size,
+            max_items=max_items,
+        )
+
+    def iter_all(
+        self,
+        *,
+        filter: str | None = None,
+        order_by: str | None = None,
+        count: bool | None = None,
+        start_skip: int = 0,
+        page_size: int = DEFAULT_PAGE_SIZE,
+        max_items: int | None = None,
+    ) -> Iterator[Account]:
+        return self._iter_all(
+            filter=filter,
+            order_by=order_by,
+            count=count,
+            start_skip=start_skip,
+            page_size=page_size,
+            max_items=max_items,
+        )
+
+    @overload
+    def create_export(
+        self: AccountsResource[Literal[False]], *, filter: str | None = None
+    ) -> ExportJobHandle[AccountExportJob]: ...
+
+    @overload
+    def create_export(
+        self: AccountsResource[Literal[True]], *, filter: str | None = None
+    ) -> ApiResponseProtocol[ExportJobHandle[AccountExportJob]]: ...
+
+    def create_export(
+        self, *, filter: str | None = None
+    ) -> ExportJobHandle[AccountExportJob] | ApiResponseProtocol[ExportJobHandle[AccountExportJob]]:
+        return self._create_export(filter=filter)
+
+    @overload
+    def get_export(
+        self: AccountsResource[Literal[False]], job_id: int
+    ) -> ExportJobHandle[AccountExportJob]: ...
+
+    @overload
+    def get_export(
+        self: AccountsResource[Literal[True]], job_id: int
+    ) -> ApiResponseProtocol[ExportJobHandle[AccountExportJob]]: ...
+
+    def get_export(
+        self, job_id: int
+    ) -> ExportJobHandle[AccountExportJob] | ApiResponseProtocol[ExportJobHandle[AccountExportJob]]:
+        return self._get_export(job_id)