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

redblack/odata.py

@@ -0,0 +1,75 @@
+"""Small, explicit helpers for RedBlack's supported OData query options.
+
+The SDK deliberately does not try to parse or validate OData expressions.
+``filter`` and ``order_by`` remain strings so callers can use server features
+that the SDK does not know about.  This module only validates the paging
+values and translates Python names to the exact wire names.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Final
+
+DEFAULT_PAGE_SIZE: Final = 200
+MAX_PAGE_SIZE: Final = 500
+
+
+def _validate_non_negative_integer(name: str, value: int | None) -> None:
+    if value is None:
+        return
+    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 or equal to zero")
+
+
+def _validate_expression(name: str, value: str | None) -> None:
+    if value is None:
+        return
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string")
+    if not value.strip():
+        raise ValueError(f"{name} must not be empty")
+
+
+@dataclass(frozen=True, slots=True)
+class ODataQuery:
+    """The OData options documented for RedBlack collection operations."""
+
+    filter: str | None = None
+    order_by: str | None = None
+    top: int | None = None
+    skip: int | None = None
+    count: bool | None = None
+
+    def __post_init__(self) -> None:
+        _validate_expression("filter", self.filter)
+        _validate_expression("order_by", self.order_by)
+        _validate_non_negative_integer("top", self.top)
+        _validate_non_negative_integer("skip", self.skip)
+        if self.top is not None and self.top > MAX_PAGE_SIZE:
+            raise ValueError(f"top must not exceed {MAX_PAGE_SIZE}")
+        if self.count is not None and not isinstance(self.count, bool):
+            raise TypeError("count must be a boolean")
+
+    def to_params(self) -> dict[str, str | int | bool]:
+        """Return exact RedBlack/OData wire query names, omitting unset values."""
+
+        params: dict[str, str | int | bool] = {}
+        if self.top is not None:
+            params["$top"] = self.top
+        if self.filter is not None:
+            params["$filter"] = self.filter
+        if self.order_by is not None:
+            params["$orderby"] = self.order_by
+        if self.count is not None:
+            params["$count"] = self.count
+        if self.skip is not None:
+            params["$skip"] = self.skip
+        return params
+
+    def with_page(self, *, top: int, skip: int) -> ODataQuery:
+        """Copy the query with paging values used for one request."""
+
+        return replace(self, top=top, skip=skip)

redblack/pagination.py

@@ -0,0 +1,184 @@
+"""Page values and bounded offset-pagination iterators."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from dataclasses import dataclass, field, replace
+from typing import Any, Generic, TypeVar, cast
+
+from .odata import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, ODataQuery
+from .response import HttpMetadata
+
+T = TypeVar("T")
+
+
+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
+
+
+@dataclass(slots=True)
+class Page(Generic[T]):
+    """One RedBlack OData page plus safe HTTP metadata."""
+
+    items: list[T]
+    total_count: int | None = None
+    skip: int = 0
+    top: int | None = None
+    http: HttpMetadata | None = None
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    @property
+    def value(self) -> list[T]:
+        """Compatibility spelling used by the wire envelope."""
+
+        return self.items
+
+    @classmethod
+    def from_data(
+        cls,
+        data: object,
+        *,
+        query: ODataQuery | None = None,
+        http: HttpMetadata | None = None,
+    ) -> Page[Any]:
+        """Coerce generated page models, mappings, or sequences into ``Page``."""
+
+        if isinstance(data, cls):
+            if data.http is None:
+                data.http = http
+            return data
+
+        raw_items = _read_member(data, "items", "value")
+        if raw_items is None and (
+            data is None
+            or isinstance(data, Mapping)
+            or not isinstance(data, Sequence)
+            or isinstance(data, str | bytes | bytearray)
+        ):
+            raw_items = []
+        elif raw_items is None:
+            raw_items = data
+
+        if isinstance(raw_items, str | bytes | bytearray) or not isinstance(raw_items, Sequence):
+            raise TypeError("collection response did not contain a sequence of items")
+
+        raw_count = _read_member(data, "total_count", "odata_count", "@odata.count")
+        total_count: int | None
+        if raw_count is None:
+            total_count = None
+        elif isinstance(raw_count, bool) or not isinstance(raw_count, int):
+            raise TypeError("collection response count was not an integer")
+        else:
+            total_count = raw_count
+
+        active_query = query or ODataQuery()
+        return cls(
+            items=list(cast(Sequence[Any], raw_items)),
+            total_count=total_count,
+            skip=active_query.skip or 0,
+            top=active_query.top,
+            http=http,
+        )
+
+
+@dataclass(slots=True)
+class Paginator(Generic[T]):
+    """Fetch pages lazily without silently loading an unbounded collection."""
+
+    fetch_page: Callable[[ODataQuery], Page[T]]
+    query: ODataQuery = field(default_factory=ODataQuery)
+    page_size: int = DEFAULT_PAGE_SIZE
+    max_items: int | None = None
+
+    def __post_init__(self) -> None:
+        if (
+            isinstance(self.page_size, bool)
+            or not isinstance(self.page_size, int)
+            or not 1 <= self.page_size <= MAX_PAGE_SIZE
+        ):
+            raise ValueError(f"page_size must be between 1 and {MAX_PAGE_SIZE}")
+        if self.max_items is not None:
+            if isinstance(self.max_items, bool) or not isinstance(self.max_items, int):
+                raise TypeError("max_items must be an integer")
+            if self.max_items < 0:
+                raise ValueError("max_items must be greater than or equal to zero")
+
+    def iter_pages(self) -> Iterator[Page[T]]:
+        if self.max_items == 0:
+            return
+
+        skip = self.query.skip or 0
+        yielded = 0
+
+        while True:
+            remaining = None if self.max_items is None else self.max_items - yielded
+            if remaining is not None and remaining <= 0:
+                return
+            request_size = self.page_size if remaining is None else min(self.page_size, remaining)
+            request_query = self.query.with_page(top=request_size, skip=skip)
+            page = self.fetch_page(request_query)
+
+            # A non-conforming server should not make max_items ineffective.
+            if remaining is not None and len(page.items) > remaining:
+                page = replace(page, items=page.items[:remaining], top=request_size)
+
+            yield page
+            received = len(page.items)
+            yielded += received
+
+            if received == 0 or received < request_size:
+                return
+            if page.total_count is not None and skip + received >= page.total_count:
+                return
+            skip += received
+
+    def iter_items(self) -> Iterator[T]:
+        for page in self.iter_pages():
+            yield from page.items
+
+
+def iter_pages(
+    fetch_page: Callable[[ODataQuery], Page[T]],
+    *,
+    query: ODataQuery | None = None,
+    page_size: int = DEFAULT_PAGE_SIZE,
+    max_items: int | None = None,
+) -> Iterator[Page[T]]:
+    """Convenience wrapper around :class:`Paginator`."""
+
+    return Paginator(
+        fetch_page=fetch_page,
+        query=query or ODataQuery(),
+        page_size=page_size,
+        max_items=max_items,
+    ).iter_pages()
+
+
+def iter_all(
+    fetch_page: Callable[[ODataQuery], Page[T]],
+    *,
+    query: ODataQuery | None = None,
+    page_size: int = DEFAULT_PAGE_SIZE,
+    max_items: int | None = None,
+) -> Iterator[T]:
+    """Yield collection items one at a time."""
+
+    return Paginator(
+        fetch_page=fetch_page,
+        query=query or ODataQuery(),
+        page_size=page_size,
+        max_items=max_items,
+    ).iter_items()

redblack/polling.py

@@ -0,0 +1,163 @@
+"""Deterministic, deadline-bounded polling for server-side workflows."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from threading import Event
+from typing import Generic, TypeVar
+
+from .errors import (
+    OperationFailedError,
+    OperationNeedsInputError,
+    PollingError,
+    PollTimeoutError,
+)
+
+T = TypeVar("T")
+
+
+class PollOutcome(str, Enum):
+    """A workflow classification independent of any one RedBlack enum."""
+
+    PENDING = "pending"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    NEEDS_INPUT = "needs_input"
+
+
+class PollingCancelledError(PollingError):
+    def __init__(self, last_value: object | None) -> None:
+        super().__init__("local polling was stopped; the server-side workflow was not canceled")
+        self.last_value = last_value
+
+
+@dataclass(frozen=True, slots=True)
+class PollPolicy:
+    """Timing policy for one synchronous wait operation."""
+
+    timeout: float | None = 300.0
+    initial_interval: float = 1.0
+    maximum_interval: float = 30.0
+    backoff_factor: float = 1.5
+
+    def __post_init__(self) -> None:
+        if self.timeout is not None and self.timeout < 0:
+            raise ValueError("timeout must be greater than or equal to zero")
+        if self.initial_interval <= 0:
+            raise ValueError("initial_interval must be greater than zero")
+        if self.maximum_interval <= 0:
+            raise ValueError("maximum_interval must be greater than zero")
+        if self.maximum_interval < self.initial_interval:
+            raise ValueError("maximum_interval must not be below initial_interval")
+        if self.backoff_factor < 1:
+            raise ValueError("backoff_factor must be at least one")
+
+
+@dataclass(slots=True)
+class Poller(Generic[T]):
+    """Refresh and classify a workflow until it reaches a terminal outcome."""
+
+    refresh: Callable[[], T]
+    classify: Callable[[T], PollOutcome]
+    suggested_delay: Callable[[T], float | None] | None = None
+    monotonic: Callable[[], float] = time.monotonic
+    sleep: Callable[[float], None] = time.sleep
+    refresh_with_timeout: Callable[[float | None], T] | None = None
+
+    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:
+        policy = PollPolicy(
+            timeout=timeout,
+            initial_interval=poll_interval,
+            maximum_interval=max_interval,
+            backoff_factor=backoff_factor,
+        )
+        started = self.monotonic()
+        deadline = None if policy.timeout is None else started + policy.timeout
+        attempt = 0
+        last_value: T | None = None
+
+        while True:
+            if stop_event is not None and stop_event.is_set():
+                raise PollingCancelledError(last_value)
+            now = self.monotonic()
+            if deadline is not None and now >= deadline:
+                raise PollTimeoutError(
+                    f"workflow did not finish within {policy.timeout!r} seconds",
+                    timeout=policy.timeout,
+                    last_value=last_value,
+                )
+
+            remaining = None if deadline is None else max(0.0, deadline - now)
+            try:
+                if self.refresh_with_timeout is None:
+                    last_value = self.refresh()
+                else:
+                    last_value = self.refresh_with_timeout(remaining)
+            except Exception:
+                if deadline is not None and self.monotonic() >= deadline:
+                    raise PollTimeoutError(
+                        f"workflow did not finish within {policy.timeout!r} seconds",
+                        timeout=policy.timeout,
+                        last_value=last_value,
+                    ) from None
+                raise
+            now = self.monotonic()
+            if deadline is not None and now >= deadline:
+                raise PollTimeoutError(
+                    f"workflow did not finish within {policy.timeout!r} seconds",
+                    timeout=policy.timeout,
+                    last_value=last_value,
+                )
+            outcome = self.classify(last_value)
+            if outcome is PollOutcome.SUCCEEDED:
+                return last_value
+            if outcome is PollOutcome.FAILED:
+                if raise_on_failure:
+                    raise OperationFailedError(
+                        "server-side workflow reached a failed terminal state",
+                        final_state=last_value,
+                    )
+                return last_value
+            if outcome is PollOutcome.NEEDS_INPUT:
+                if raise_on_failure:
+                    raise OperationNeedsInputError(
+                        "server-side workflow stopped and requires caller input",
+                        final_state=last_value,
+                    )
+                return last_value
+
+            exponential_delay = min(
+                policy.maximum_interval,
+                policy.initial_interval * (policy.backoff_factor**attempt),
+            )
+            requested_delay = (
+                None if self.suggested_delay is None else self.suggested_delay(last_value)
+            )
+            if requested_delay is not None and requested_delay <= 0:
+                requested_delay = None
+            delay = (
+                exponential_delay
+                if requested_delay is None
+                else max(0.0, min(policy.maximum_interval, requested_delay))
+            )
+            if deadline is not None:
+                delay = min(delay, max(0.0, deadline - now))
+
+            if stop_event is not None:
+                if stop_event.wait(delay):
+                    raise PollingCancelledError(last_value)
+            else:
+                self.sleep(delay)
+            attempt += 1

redblack/py.typed

@@ -0,0 +1 @@
+

redblack/raw.py

@@ -0,0 +1,102 @@
+"""Constrained access to RedBlack endpoints not yet modeled by the SDK."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Protocol
+from urllib.parse import urlsplit
+
+from .response import ApiResponse
+
+_PROTECTED_HEADERS = frozenset(
+    {
+        "accept-version",
+        "authorization",
+        "client-id",
+        "cookie",
+        "host",
+        "proxy-authorization",
+        "x-api-key",
+    }
+)
+ExpectedStatuses = Sequence[int] | set[int] | frozenset[int]
+
+
+class _RawTransport(Protocol):
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, object] | None = None,
+        headers: Mapping[str, str] | None = None,
+        content: bytes | str | None = None,
+        expected_statuses: ExpectedStatuses | None = None,
+        authenticated: bool = True,
+        allow_retry: bool | None = None,
+        api_version: str | None = None,
+    ) -> ApiResponse[bytes]: ...
+
+
+class RawClient:
+    """Send a same-origin request through the configured SDK transport.
+
+    This is an escape hatch for a future RedBlack operation. It deliberately
+    accepts only relative API paths and does not permit callers to replace
+    credential-bearing headers.
+    """
+
+    def __init__(self, transport: _RawTransport) -> None:
+        self._transport = transport
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, object] | None = None,
+        headers: Mapping[str, str] | None = None,
+        content: bytes | str | None = None,
+        expected_statuses: ExpectedStatuses | None = None,
+        api_version: str | None = None,
+        authenticated: bool = True,
+        allow_retry: bool | None = None,
+    ) -> ApiResponse[bytes]:
+        """Send a raw request while retaining SDK auth, errors, and retries."""
+
+        _validate_relative_path(path)
+        request_headers = dict(headers or {})
+        overridden = sorted(
+            name for name in request_headers if name.strip().lower() in _PROTECTED_HEADERS
+        )
+        if overridden:
+            names = ", ".join(overridden)
+            raise ValueError(f"raw requests cannot override protected headers: {names}")
+        return self._transport.request(
+            method=method,
+            path=path,
+            params=params,
+            headers=request_headers,
+            content=content,
+            expected_statuses=expected_statuses,
+            authenticated=authenticated,
+            allow_retry=allow_retry,
+            api_version=api_version,
+        )
+
+
+def _validate_relative_path(path: str) -> None:
+    if not isinstance(path, str) or not path:
+        raise ValueError("raw request path must be a non-empty string")
+    parsed = urlsplit(path)
+    if (
+        parsed.scheme
+        or parsed.netloc
+        or not parsed.path.startswith("/")
+        or parsed.path.startswith("//")
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError("raw requests require a relative same-origin API path")
+    if "\\" in path or any(ord(character) < 32 for character in path):
+        raise ValueError("raw request path contains unsafe characters")

redblack/resources/__init__.py

@@ -0,0 +1,65 @@
+"""Public RedBlack endpoint groups and workflow handles."""
+
+from ._base import ClientProtocol, VersionedResource
+from ._exports import ExportJobHandle, WorkflowProtocolError
+from .accounts import AccountsResource
+from .cash_actions import (
+    CONFIRM_DELETE_ALL_CASH_ACTIONS,
+    CashActionsResource,
+)
+from .equivalents import EquivalentsResource
+from .households import HouseholdsResource
+from .orders import OrdersResource
+from .restrictions import RestrictionsResource
+from .review_sets import (
+    OrderAddSessionHandle,
+    ReleaseCriteria,
+    ReleaseSessionHandle,
+    ReviewSetsResource,
+)
+from .securities import SecuritiesResource
+from .tasks import TasksResource
+from .users import UsersResource
+
+RESOURCE_CLASSES = (
+    AccountsResource,
+    HouseholdsResource,
+    OrdersResource,
+    RestrictionsResource,
+    EquivalentsResource,
+    CashActionsResource,
+    SecuritiesResource,
+    ReviewSetsResource,
+    UsersResource,
+    TasksResource,
+)
+
+IMPLEMENTED_OPERATION_IDS = frozenset().union(
+    *(resource.OPERATION_IDS for resource in RESOURCE_CLASSES)
+)
+"""Every 2026.3.0 operation reached through a public resource or handle."""
+
+if len(IMPLEMENTED_OPERATION_IDS) != 44:  # pragma: no cover - import invariant
+    raise RuntimeError("resource operation inventory must contain exactly 44 unique operations")
+
+__all__ = [
+    "AccountsResource",
+    "CONFIRM_DELETE_ALL_CASH_ACTIONS",
+    "CashActionsResource",
+    "ClientProtocol",
+    "EquivalentsResource",
+    "ExportJobHandle",
+    "HouseholdsResource",
+    "IMPLEMENTED_OPERATION_IDS",
+    "OrderAddSessionHandle",
+    "OrdersResource",
+    "ReleaseCriteria",
+    "ReleaseSessionHandle",
+    "RestrictionsResource",
+    "ReviewSetsResource",
+    "SecuritiesResource",
+    "TasksResource",
+    "UsersResource",
+    "VersionedResource",
+    "WorkflowProtocolError",
+]