autoassembler 0.3.1__py3-none-any.whl

autoassembler/_custom/http.py

@@ -0,0 +1,42 @@
+"""Reading a response the way the generated clients do, for requests sent by hand.
+
+Hand-written, protected via `.fernignore`.
+"""
+
+import typing
+from json.decoder import JSONDecodeError
+
+import httpx
+from pydantic import ValidationError
+
+from ..core.api_error import ApiError
+from ..core.parse_error import ParsingError
+from ..core.pydantic_utilities import parse_obj_as
+from ..errors.bad_request_error import BadRequestError
+from ..errors.forbidden_error import ForbiddenError
+from ..errors.not_found_error import NotFoundError
+
+
+def parsed[T](response: httpx.Response, type_: type[T]) -> T:
+    """``response`` as a ``type_``, or the error the generated client raises for its status."""
+    try:
+        body = response.json()
+    except JSONDecodeError:
+        raise ApiError(
+            status_code=response.status_code, headers=dict(response.headers), body=response.text
+        ) from None
+    headers = dict(response.headers)
+    if 200 <= response.status_code < 300:
+        try:
+            return typing.cast(T, parse_obj_as(type_, body))
+        except ValidationError as error:
+            raise ParsingError(
+                status_code=response.status_code, headers=headers, body=body, cause=error
+            ) from error
+    if response.status_code == 400:
+        raise BadRequestError(headers=headers, body=body)
+    if response.status_code == 403:
+        raise ForbiddenError(headers=headers, body=body)
+    if response.status_code == 404:
+        raise NotFoundError(headers=headers, body=body)
+    raise ApiError(status_code=response.status_code, headers=headers, body=body)

autoassembler/_custom/operations.py

@@ -0,0 +1,258 @@
+"""Custom Operations namespace — hand-written, protected via `.fernignore`.
+
+`Operations` subclasses the generated `OperationsClient` and adds `handle`, which wraps an
+operation in an `Operation` that refreshes itself through this client.
+
+It also replaces `get_operation` and `list_operations`, the calls that can see operations
+this SDK did not start: the generated unions of operation kinds are closed, so one kind
+added to the server would make them fail. Here a kind this SDK version does not know comes
+back as `UnknownOperationMetadata` / `UnknownOperationResponse` (its ``type`` and raw
+fields); known kinds parse, and are validated, exactly as generated.
+"""
+
+import typing
+
+import pydantic
+
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.jsonable_encoder import encode_path_param
+from ..core.pydantic_utilities import UniversalBaseModel
+from ..core.request_options import RequestOptions
+from ..operation import AsyncOperation, Operation, operation_id
+from ..operations.client import AsyncOperationsClient, OperationsClient
+from ..types.list_operations_response import ListOperationsResponse
+from ..types.operation import Operation as OperationResource
+from ..types.operation_metadata import OperationMetadata
+from ..types.operation_response import OperationResponse
+from .http import parsed
+
+_OPERATIONS_PATH = "api/v4/operations"
+_UNKNOWN = "unknown"
+
+
+class UnknownOperationMetadata(UniversalBaseModel):
+    """Metadata of an operation kind this SDK version does not know: from a newer server.
+
+    ``type`` is ``None`` when the server sent none (operations stored by early server builds).
+    """
+
+    type: str | None = None
+    model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+        extra="allow", frozen=True
+    )
+
+
+class UnknownOperationResponse(UniversalBaseModel):
+    """Response of an operation kind this SDK version does not know; ``type`` as in the metadata."""
+
+    type: str | None = None
+    model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(
+        extra="allow", frozen=True
+    )
+
+
+def _open(closed: typing.Any, unknown: type) -> typing.Any:
+    """``closed``, a generated union discriminated by ``type``, plus ``unknown`` for any other type.
+
+    Routing on ``type`` keeps a known kind strict: a broken body still fails to parse.
+    """
+    variants = typing.get_args(typing.get_args(closed)[0])
+    known = {typing.get_args(v.model_fields["type"].annotation)[0]: v for v in variants}
+
+    def tag(value: typing.Any) -> str:
+        kind = value.get("type") if isinstance(value, dict) else getattr(value, "type", None)
+        return kind if isinstance(kind, str) and kind in known else _UNKNOWN
+
+    return typing.Annotated[
+        typing.Union[  # noqa: UP007 (built from a runtime list)
+            tuple(
+                [
+                    *(typing.Annotated[v, pydantic.Tag(t)] for t, v in known.items()),
+                    typing.Annotated[unknown, pydantic.Tag(_UNKNOWN)],
+                ]
+            )
+        ],
+        pydantic.Discriminator(tag),
+    ]
+
+
+class AnyOperation(OperationResource):
+    """A server operation of any kind, as `get_operation` and `list_operations` return it.
+
+    The generated model (`autoassembler.types.Operation`) accepts only the operation kinds in
+    this SDK's spec, so reading a kind the server added later fails the whole call. This
+    subclass widens its two kind-specific fields: a known ``type`` still parses, strictly, to
+    its generated class; any other ``type`` (or none) to `UnknownOperationMetadata` /
+    `UnknownOperationResponse`, which keep the raw fields. Everything else is the generated
+    model's, so an `AnyOperation` goes wherever one is expected.
+
+    Type checkers see the plain union; pydantic sees the union routed on ``type`` (`_open`).
+    """
+
+    if typing.TYPE_CHECKING:
+        metadata: OperationMetadata | UnknownOperationMetadata  # pyright: ignore[reportIncompatibleVariableOverride]
+        response: OperationResponse | UnknownOperationResponse | None = None  # pyright: ignore[reportIncompatibleVariableOverride]
+    else:
+        metadata: _open(OperationMetadata, UnknownOperationMetadata)
+        response: _open(OperationResponse, UnknownOperationResponse) | None = None
+
+
+class OperationsPage(ListOperationsResponse):
+    """A page of `list_operations`, whose operations may be of kinds this SDK does not know."""
+
+    operations: list[AnyOperation]  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+def _list_params(page_size: int | None, page_token: str | None) -> dict[str, typing.Any]:
+    return {"pageSize": page_size, "pageToken": page_token}
+
+
+def response_of[R](type_: type[R]) -> typing.Callable[[OperationResource], R]:
+    """A `resolve` returning the finished operation's response, which must be a ``type_``."""
+
+    def resolve(operation: OperationResource) -> R:
+        if not isinstance(operation.response, type_):
+            raise TypeError(f"{operation.name} responded with {type(operation.response).__name__}")
+        return operation.response
+
+    return resolve
+
+
+def async_response_of[R](
+    type_: type[R],
+) -> typing.Callable[[OperationResource], typing.Awaitable[R]]:
+    """The async form of `response_of`."""
+    resolve = response_of(type_)
+
+    async def resolve_async(operation: OperationResource) -> R:
+        return resolve(operation)
+
+    return resolve_async
+
+
+class Operations(OperationsClient):
+    """Generated operations client + `handle`, reading kinds this SDK does not know."""
+
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        super().__init__(client_wrapper=client_wrapper)
+        self._client_wrapper = client_wrapper
+
+    def get_operation(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, id: str, *, request_options: RequestOptions | None = None
+    ) -> AnyOperation:
+        """The operation ``operations/{id}``, of any kind."""
+        response = self._client_wrapper.httpx_client.request(
+            f"{_OPERATIONS_PATH}/{encode_path_param(id)}",
+            method="GET",
+            request_options=request_options,
+        )
+        return parsed(response, AnyOperation)
+
+    def list_operations(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        *,
+        page_size: int | None = None,
+        page_token: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> OperationsPage:
+        """The caller's operations, newest first, of any kind; see the generated call."""
+        response = self._client_wrapper.httpx_client.request(
+            _OPERATIONS_PATH,
+            method="GET",
+            params=_list_params(page_size, page_token),
+            request_options=request_options,
+        )
+        return parsed(response, OperationsPage)
+
+    @typing.overload
+    def handle(
+        self, operation: OperationResource | str
+    ) -> Operation[OperationResponse | UnknownOperationResponse]: ...
+    @typing.overload
+    def handle[T](
+        self,
+        operation: OperationResource | str,
+        *,
+        resolve: typing.Callable[[OperationResource], T],
+    ) -> Operation[T]: ...
+    def handle(
+        self,
+        operation: OperationResource | str,
+        *,
+        resolve: typing.Callable[[OperationResource], typing.Any] | None = None,
+    ) -> Operation[typing.Any]:
+        """An `Operation` for ``operation``: one an endpoint returned, or the name of one.
+
+        ``resolve`` maps the finished operation to the result; by default it is the response.
+        """
+        if isinstance(operation, str):
+            operation = self.get_operation(operation_id(operation))
+        name = operation.name
+        return Operation(
+            operation, refresh=lambda: self.get_operation(operation_id(name)), resolve=resolve
+        )
+
+
+class AsyncOperations(AsyncOperationsClient):
+    """Async generated operations client + `handle` (mirror of `Operations`)."""
+
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        super().__init__(client_wrapper=client_wrapper)
+        self._client_wrapper = client_wrapper
+
+    async def get_operation(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, id: str, *, request_options: RequestOptions | None = None
+    ) -> AnyOperation:
+        """The operation ``operations/{id}``, of any kind."""
+        response = await self._client_wrapper.httpx_client.request(
+            f"{_OPERATIONS_PATH}/{encode_path_param(id)}",
+            method="GET",
+            request_options=request_options,
+        )
+        return parsed(response, AnyOperation)
+
+    async def list_operations(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        *,
+        page_size: int | None = None,
+        page_token: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> OperationsPage:
+        """The caller's operations, newest first, of any kind; see `Operations.list_operations`."""
+        response = await self._client_wrapper.httpx_client.request(
+            _OPERATIONS_PATH,
+            method="GET",
+            params=_list_params(page_size, page_token),
+            request_options=request_options,
+        )
+        return parsed(response, OperationsPage)
+
+    @typing.overload
+    async def handle(
+        self, operation: OperationResource | str
+    ) -> AsyncOperation[OperationResponse | UnknownOperationResponse]: ...
+    @typing.overload
+    async def handle[T](
+        self,
+        operation: OperationResource | str,
+        *,
+        resolve: typing.Callable[[OperationResource], typing.Awaitable[T]],
+    ) -> AsyncOperation[T]: ...
+    async def handle(
+        self,
+        operation: OperationResource | str,
+        *,
+        resolve: typing.Callable[[OperationResource], typing.Awaitable[typing.Any]] | None = None,
+    ) -> AsyncOperation[typing.Any]:
+        """An `AsyncOperation` for ``operation``; see `Operations.handle`.
+
+        A coroutine, since a name is first fetched.
+        """
+        if isinstance(operation, str):
+            operation = await self.get_operation(operation_id(operation))
+        name = operation.name
+
+        async def refresh() -> OperationResource:
+            return await self.get_operation(operation_id(name))
+
+        return AsyncOperation(operation, refresh=refresh, resolve=resolve)