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

redblack/client.py

@@ -0,0 +1,512 @@
+"""Public synchronous RedBlack client."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Mapping
+from decimal import Decimal
+from enum import Enum
+from types import TracebackType
+from typing import Any, Literal, Self
+from urllib.parse import quote
+
+import httpx
+
+from ._generated.contract import (
+    encode_request,
+    get_operation_spec,
+    parse_response,
+)
+from ._version import SUPPORTED_API_VERSION
+from .auth import TokenProvider
+from .config import (
+    Environment,
+    PasswordCredentials,
+    RedBlackConfig,
+    RetryConfig,
+    TimeoutConfig,
+    VerifyValue,
+)
+from .errors import ConfigurationError, ResponseDecodeError
+from .raw import RawClient
+from .resources import (
+    AccountsResource,
+    CashActionsResource,
+    EquivalentsResource,
+    HouseholdsResource,
+    OrdersResource,
+    RestrictionsResource,
+    ReviewSetsResource,
+    SecuritiesResource,
+    TasksResource,
+    UsersResource,
+)
+from .response import ApiResponse
+from .transport import HttpxTransport
+
+_PATH_PARAMETER = re.compile(r"\{([^{}]+)\}")
+_MANAGED_HEADERS = frozenset(
+    {"accept-version", "authorization", "client-id", "content-type", "x-api-key"}
+)
+
+
+class RedBlackClient:
+    """Synchronous, typed client for RedBlack API release 2026.3.0.
+
+    The normal constructor is intentionally explicit and reads neither process
+    variables nor dotenv files. Use :meth:`from_env` or :meth:`from_dotenv`
+    when configuration lookup is desired.
+    """
+
+    config: RedBlackConfig
+    accounts: AccountsResource[Literal[False]]
+    households: HouseholdsResource[Literal[False]]
+    restrictions: RestrictionsResource[Literal[False]]
+    equivalents: EquivalentsResource[Literal[False]]
+    cash_actions: CashActionsResource[Literal[False]]
+    securities: SecuritiesResource[Literal[False]]
+    review_sets: ReviewSetsResource[Literal[False]]
+    users: UsersResource[Literal[False]]
+    orders: OrdersResource[Literal[False]]
+    tasks: TasksResource[Literal[False]]
+    with_http_info: HttpInfoClient
+    raw: RawClient
+
+    def __init__(
+        self,
+        *,
+        environment: Environment | str,
+        api_key: str,
+        client_id: str,
+        api_version: str = SUPPORTED_API_VERSION,
+        credentials: PasswordCredentials | None = None,
+        access_token: str | None = None,
+        token_provider: TokenProvider | None = None,
+        base_url: str | None = None,
+        timeout: TimeoutConfig | None = None,
+        retry: RetryConfig | None = None,
+        verify: VerifyValue = True,
+        proxy: str | None = None,
+        trust_env: bool = False,
+        allow_insecure_transport: bool = False,
+        allow_unsupported_api_version: bool = False,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if token_provider is not None and (credentials is not None or access_token is not None):
+            raise ConfigurationError(
+                "token_provider cannot be combined with credentials or access_token"
+            )
+        config = RedBlackConfig(
+            environment=environment,
+            api_key=api_key,
+            client_id=client_id,
+            api_version=api_version,
+            credentials=credentials,
+            access_token=access_token,
+            base_url=base_url,
+            timeout=timeout or TimeoutConfig(),
+            retry=retry or RetryConfig(),
+            verify=verify,
+            proxy=proxy,
+            trust_env=trust_env,
+            allow_insecure_transport=allow_insecure_transport,
+            allow_unsupported_api_version=allow_unsupported_api_version,
+        )
+        self._initialize(
+            config,
+            token_provider=token_provider,
+            http_client=http_client,
+        )
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        environ: Mapping[str, str] | None = None,
+        token_provider: TokenProvider | None = None,
+        http_client: httpx.Client | None = None,
+        **overrides: Any,
+    ) -> Self:
+        """Build a client from explicit overrides, then process variables."""
+
+        config = RedBlackConfig.from_env(
+            environ=environ,
+            require_auth=token_provider is None,
+            **overrides,
+        )
+        return cls._from_config(
+            config,
+            token_provider=token_provider,
+            http_client=http_client,
+        )
+
+    @classmethod
+    def from_dotenv(
+        cls,
+        path: str | os.PathLike[str] | None = None,
+        *,
+        search_start: str | os.PathLike[str] | None = None,
+        environ: Mapping[str, str] | None = None,
+        token_provider: TokenProvider | None = None,
+        http_client: httpx.Client | None = None,
+        **overrides: Any,
+    ) -> Self:
+        """Build a client with explicit > environment > dotenv precedence."""
+
+        config = RedBlackConfig.from_dotenv(
+            path,
+            search_start=search_start,
+            environ=environ,
+            require_auth=token_provider is None,
+            **overrides,
+        )
+        return cls._from_config(
+            config,
+            token_provider=token_provider,
+            http_client=http_client,
+        )
+
+    @classmethod
+    def _from_config(
+        cls,
+        config: RedBlackConfig,
+        *,
+        token_provider: TokenProvider | None,
+        http_client: httpx.Client | None,
+    ) -> Self:
+        instance = cls.__new__(cls)
+        instance._initialize(
+            config,
+            token_provider=token_provider,
+            http_client=http_client,
+        )
+        return instance
+
+    def _initialize(
+        self,
+        config: RedBlackConfig,
+        *,
+        token_provider: TokenProvider | None,
+        http_client: httpx.Client | None,
+    ) -> None:
+        if token_provider is not None and config.auth_mode is not None:
+            raise ConfigurationError(
+                "token_provider cannot be combined with built-in authentication"
+            )
+
+        owns_token_provider = token_provider is None
+        resolved_provider = token_provider or config.build_token_provider(http_client=http_client)
+        try:
+            transport = HttpxTransport(
+                config,
+                resolved_provider,
+                client=http_client,
+            )
+        except BaseException:
+            if owns_token_provider:
+                close = getattr(resolved_provider, "close", None)
+                if callable(close):
+                    close()
+            raise
+
+        self.config = config
+        self._token_provider = resolved_provider
+        self._owns_token_provider = owns_token_provider
+        self._transport = transport
+        self._closed = False
+        self.raw = RawClient(transport)
+        self.accounts = AccountsResource(self)
+        self.households = HouseholdsResource(self)
+        self.restrictions = RestrictionsResource(self)
+        self.equivalents = EquivalentsResource(self)
+        self.cash_actions = CashActionsResource(self)
+        self.securities = SecuritiesResource(self)
+        self.review_sets = ReviewSetsResource(self)
+        self.users = UsersResource(self)
+        self.orders = OrdersResource(self)
+        self.tasks = TasksResource(self)
+        self.with_http_info = HttpInfoClient(self)
+
+    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]:
+        """Execute one captured operation and return data with HTTP metadata.
+
+        Resource facades call this operation-level method. It is also useful to
+        advanced callers who know a RedBlack ``operationId`` but want to retain
+        generated validation and response parsing.
+
+        ``timeout_budget`` limits transport work for this call in seconds.
+        """
+
+        if self.config.api_version != SUPPORTED_API_VERSION:
+            raise ConfigurationError(
+                f"typed calls require API {SUPPORTED_API_VERSION}; "
+                "use client.raw for an explicitly unsupported version"
+            )
+        if not isinstance(stream, bool):
+            raise TypeError("stream must be a bool")
+
+        operation = get_operation_spec(operation_id)
+        path = _render_path(operation.path, operation.parameters, path_params)
+        params = _render_query(operation.parameters, query)
+        encoded = encode_request(operation_id, json)
+        request_headers = _render_headers(
+            operation.parameters,
+            headers,
+            has_body=encoded is not None,
+        )
+
+        raw_response = self._transport.request(
+            operation.method,
+            path,
+            params=params,
+            headers=request_headers,
+            content=encoded,
+            expected_statuses=operation.success_statuses,
+            authenticated=True,
+            operation_id=operation_id,
+            timeout_budget=timeout_budget,
+        )
+        content_type = raw_response.headers.get("content-type")
+        try:
+            parsed = parse_response(
+                operation_id,
+                raw_response.status_code,
+                raw_response.raw,
+                content_type,
+            )
+        except (TypeError, ValueError):
+            raise ResponseDecodeError(
+                "RedBlack success response did not match the captured contract",
+                status_code=raw_response.status_code,
+                method=operation.method,
+                path=operation_id,
+                request_id=raw_response.request_id,
+                raw_body=raw_response.raw,
+            ) from None
+
+        attach_http = getattr(parsed, "_attach_http", None)
+        if callable(attach_http):
+            parsed = attach_http(raw_response.http)
+        return raw_response.with_data(parsed)
+
+    def close(self) -> None:
+        """Close SDK-owned HTTP resources; caller-injected clients stay open."""
+
+        if self._closed:
+            return
+        self._closed = True
+        self._transport.close()
+        if self._owns_token_provider:
+            close = getattr(self._token_provider, "close", None)
+            if callable(close):
+                close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        del exc_type, exc_value, traceback
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"RedBlackClient(config={self.config!r}, closed={self._closed!r})"
+
+
+class HttpInfoClient:
+    """View whose direct resource requests return :class:`ApiResponse`.
+
+    Lazy iterator helpers still yield their documented pages or item values.
+    """
+
+    accounts: AccountsResource[Literal[True]]
+    households: HouseholdsResource[Literal[True]]
+    restrictions: RestrictionsResource[Literal[True]]
+    equivalents: EquivalentsResource[Literal[True]]
+    cash_actions: CashActionsResource[Literal[True]]
+    securities: SecuritiesResource[Literal[True]]
+    review_sets: ReviewSetsResource[Literal[True]]
+    users: UsersResource[Literal[True]]
+    orders: OrdersResource[Literal[True]]
+    tasks: TasksResource[Literal[True]]
+
+    def __init__(self, client: RedBlackClient) -> None:
+        self._client = client
+        self.accounts = AccountsResource(client, with_http_info=True)
+        self.households = HouseholdsResource(client, with_http_info=True)
+        self.restrictions = RestrictionsResource(client, with_http_info=True)
+        self.equivalents = EquivalentsResource(client, with_http_info=True)
+        self.cash_actions = CashActionsResource(client, with_http_info=True)
+        self.securities = SecuritiesResource(client, with_http_info=True)
+        self.review_sets = ReviewSetsResource(client, with_http_info=True)
+        self.users = UsersResource(client, with_http_info=True)
+        self.orders = OrdersResource(client, with_http_info=True)
+        self.tasks = TasksResource(client, with_http_info=True)
+
+    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]:
+        """Delegate an operation-level request to the owning client."""
+
+        return self._client.request(
+            operation_id,
+            path_params=path_params,
+            query=query,
+            headers=headers,
+            json=json,
+            stream=stream,
+            timeout_budget=timeout_budget,
+        )
+
+
+def _render_path(
+    template: str,
+    parameters: tuple[Any, ...],
+    supplied: Mapping[str, object] | None,
+) -> str:
+    expected = _PATH_PARAMETER.findall(template)
+    values = dict(supplied or {})
+    aliases = {
+        parameter.python_name: parameter.wire_name
+        for parameter in parameters
+        if parameter.location == "path" and parameter.python_name != parameter.wire_name
+    }
+    for python_name, wire_name in aliases.items():
+        if python_name in values:
+            if wire_name in values:
+                raise TypeError(
+                    f"path parameter {wire_name!r} was supplied by both wire and Python name"
+                )
+            values[wire_name] = values.pop(python_name)
+
+    missing = [name for name in expected if name not in values]
+    extra = sorted(set(values) - set(expected))
+    if missing:
+        raise TypeError(f"missing path parameter(s): {', '.join(missing)}")
+    if extra:
+        raise TypeError(f"unknown path parameter(s): {', '.join(extra)}")
+
+    def replacement(match: re.Match[str]) -> str:
+        name = match.group(1)
+        value = values[name]
+        if value is None:
+            raise TypeError(f"path parameter {name!r} cannot be None")
+        if isinstance(value, Enum):
+            value = value.value
+        return quote(str(value), safe="-._~")
+
+    return _PATH_PARAMETER.sub(replacement, template)
+
+
+def _render_query(
+    parameters: tuple[Any, ...],
+    supplied: Mapping[str, object] | None,
+) -> dict[str, object]:
+    values = dict(supplied or {})
+    query_parameters = {
+        parameter.wire_name: parameter for parameter in parameters if parameter.location == "query"
+    }
+    aliases = {
+        parameter.python_name: parameter.wire_name
+        for parameter in query_parameters.values()
+        if parameter.python_name != parameter.wire_name
+    }
+    rendered: dict[str, object] = {}
+    for name, value in values.items():
+        wire_name = aliases.get(name, name)
+        if wire_name not in query_parameters:
+            raise TypeError(f"unknown query parameter: {name}")
+        if wire_name in rendered:
+            raise TypeError(f"query parameter {wire_name!r} was supplied twice")
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            rendered[wire_name] = "true" if value else "false"
+        elif isinstance(value, Enum):
+            rendered[wire_name] = value.value
+        elif isinstance(value, Decimal):
+            rendered[wire_name] = str(value)
+        else:
+            rendered[wire_name] = value
+
+    missing = [
+        name
+        for name, parameter in query_parameters.items()
+        if parameter.required and name not in rendered
+    ]
+    if missing:
+        raise TypeError(f"missing query parameter(s): {', '.join(missing)}")
+    return rendered
+
+
+def _render_headers(
+    parameters: tuple[Any, ...],
+    supplied: Mapping[str, str] | None,
+    *,
+    has_body: bool,
+) -> dict[str, str]:
+    header_parameters = {
+        parameter.wire_name.casefold(): parameter
+        for parameter in parameters
+        if parameter.location == "header"
+    }
+    aliases = {
+        parameter.python_name: parameter.wire_name
+        for parameter in header_parameters.values()
+        if parameter.python_name != parameter.wire_name
+    }
+    rendered: dict[str, str] = {}
+    rendered_names: set[str] = set()
+    for name, value in (supplied or {}).items():
+        if not isinstance(name, str) or not isinstance(value, str):
+            raise TypeError("header names and values must be strings")
+        if name.casefold() in _MANAGED_HEADERS:
+            raise ConfigurationError(f"request header {name!r} is managed by the SDK")
+        wire_name = aliases.get(name, name)
+        parameter = header_parameters.get(wire_name.casefold())
+        if parameter is None:
+            raise TypeError(f"unknown operation header: {name}")
+        normalized = parameter.wire_name.casefold()
+        if normalized in rendered_names:
+            raise TypeError(f"header {parameter.wire_name!r} was supplied twice")
+        rendered[parameter.wire_name] = value
+        rendered_names.add(normalized)
+
+    missing = [
+        parameter.wire_name
+        for parameter in header_parameters.values()
+        if parameter.required
+        and parameter.wire_name.casefold() not in _MANAGED_HEADERS
+        and parameter.wire_name.casefold() not in rendered_names
+    ]
+    if missing:
+        raise TypeError(f"missing operation header(s): {', '.join(missing)}")
+    if has_body:
+        rendered["Content-Type"] = "application/json"
+    return rendered
+
+
+__all__ = ["HttpInfoClient", "RedBlackClient"]