autoassembler 0.3.1__py3-none-any.whl

autoassembler/core/serialization.py

@@ -0,0 +1,347 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import collections
+import inspect
+import typing
+
+import pydantic
+import typing_extensions
+
+
+class FieldMetadata:
+    """
+    Metadata class used to annotate fields to provide additional information.
+
+    Example:
+    class MyDict(TypedDict):
+        field: typing.Annotated[str, FieldMetadata(alias="field_name")]
+
+    Will serialize: `{"field": "value"}`
+    To: `{"field_name": "value"}`
+    """
+
+    alias: str
+
+    def __init__(self, *, alias: str) -> None:
+        self.alias = alias
+
+
+# Resolving type hints (typing.get_type_hints) is expensive because it eval/compiles
+# forward-reference annotations. The result is constant for a given type, so we cache it.
+# This is critical for hot paths like SSE event parsing, where the same (often large
+# discriminated-union) type is converted on every single event.
+_type_hints_cache: typing.Dict[typing.Any, typing.Dict[str, typing.Any]] = {}
+
+
+def _get_cached_type_hints(expected_type: typing.Any) -> typing.Dict[str, typing.Any]:
+    try:
+        cached = _type_hints_cache.get(expected_type)
+    except TypeError:
+        # Unhashable type; resolve without caching.
+        return _resolve_type_hints(expected_type)
+    if cached is None:
+        cached = _resolve_type_hints(expected_type)
+        _type_hints_cache[expected_type] = cached
+    return cached
+
+
+def _resolve_type_hints(expected_type: typing.Any) -> typing.Dict[str, typing.Any]:
+    try:
+        return typing_extensions.get_type_hints(expected_type, include_extras=True)
+    except NameError:
+        # The type contains a circular reference, so we use the __annotations__ attribute directly.
+        return getattr(expected_type, "__annotations__", {})
+
+
+# Whether convert_and_respect_annotation_metadata can possibly rewrite anything for a given
+# annotation, i.e. whether any reachable model/TypedDict field carries a FieldMetadata alias.
+# This is constant per type, so we cache it and use it to short-circuit the recursive walk.
+_requires_conversion_cache: typing.Dict[typing.Any, bool] = {}
+
+
+def _requires_conversion(type_: typing.Any) -> bool:
+    try:
+        cached = _requires_conversion_cache.get(type_)
+    except TypeError:
+        # Unhashable annotation; compute without caching.
+        return _compute_requires_conversion(type_, set())
+    if cached is None:
+        cached = _compute_requires_conversion(type_, set())
+        _requires_conversion_cache[type_] = cached
+    return cached
+
+
+def _compute_requires_conversion(type_: typing.Any, seen: typing.Set[typing.Any]) -> bool:
+    clean_type = _remove_annotations(type_)
+
+    try:
+        if clean_type in seen:
+            return False
+        seen = seen | {clean_type}
+    except TypeError:
+        # Unhashable type; skip cycle tracking (the type graph is finite in practice).
+        pass
+
+    # Models / TypedDicts: a field alias here means we must dealias; otherwise recurse into fields.
+    if (inspect.isclass(clean_type) and issubclass(clean_type, pydantic.BaseModel)) or typing_extensions.is_typeddict(
+        clean_type
+    ):
+        annotations = _get_cached_type_hints(clean_type)
+        if _get_alias_to_field_name(annotations):
+            return True
+        return any(_compute_requires_conversion(hint, seen) for hint in annotations.values())
+
+    # Containers / unions: recurse into the type arguments (List/Set/Sequence/Dict/Union/etc.).
+    return any(_compute_requires_conversion(arg, seen) for arg in typing_extensions.get_args(clean_type))
+
+
+def convert_and_respect_annotation_metadata(
+    *,
+    object_: typing.Any,
+    annotation: typing.Any,
+    inner_type: typing.Optional[typing.Any] = None,
+    direction: typing.Literal["read", "write"],
+) -> typing.Any:
+    """
+    Respect the metadata annotations on a field, such as aliasing. This function effectively
+    manipulates the dict-form of an object to respect the metadata annotations. This is primarily used for
+    TypedDicts, which cannot support aliasing out of the box, and can be extended for additional
+    utilities, such as defaults.
+
+    Parameters
+    ----------
+    object_ : typing.Any
+
+    annotation : type
+        The type we're looking to apply typing annotations from
+
+    inner_type : typing.Optional[type]
+
+    Returns
+    -------
+    typing.Any
+    """
+
+    if object_ is None:
+        return None
+    if inner_type is None:
+        inner_type = annotation
+        # The only thing this function ever rewrites is keys that carry a FieldMetadata
+        # alias. If nothing in the (cached) type graph has such an alias, the conversion is
+        # a content-identity transform, so we can skip the entire recursive walk. This is
+        # the hot path for SSE streaming, where a large discriminated union would otherwise
+        # be traversed on every single event.
+        if not _requires_conversion(annotation):
+            return object_
+
+    clean_type = _remove_annotations(inner_type)
+    # Pydantic models
+    if (
+        inspect.isclass(clean_type)
+        and issubclass(clean_type, pydantic.BaseModel)
+        and isinstance(object_, typing.Mapping)
+    ):
+        return _convert_mapping(object_, clean_type, direction)
+    # TypedDicts
+    if typing_extensions.is_typeddict(clean_type) and isinstance(object_, typing.Mapping):
+        return _convert_mapping(object_, clean_type, direction)
+
+    if (
+        typing_extensions.get_origin(clean_type) == typing.Dict
+        or typing_extensions.get_origin(clean_type) == dict
+        or clean_type == typing.Dict
+    ) and isinstance(object_, typing.Dict):
+        key_type = typing_extensions.get_args(clean_type)[0]
+        value_type = typing_extensions.get_args(clean_type)[1]
+
+        return {
+            key: convert_and_respect_annotation_metadata(
+                object_=value,
+                annotation=annotation,
+                inner_type=value_type,
+                direction=direction,
+            )
+            for key, value in object_.items()
+        }
+
+    # If you're iterating on a string, do not bother to coerce it to a sequence.
+    if not isinstance(object_, str):
+        if (
+            typing_extensions.get_origin(clean_type) == typing.Set
+            or typing_extensions.get_origin(clean_type) == set
+            or clean_type == typing.Set
+        ) and isinstance(object_, typing.Set):
+            inner_type = typing_extensions.get_args(clean_type)[0]
+            return {
+                convert_and_respect_annotation_metadata(
+                    object_=item,
+                    annotation=annotation,
+                    inner_type=inner_type,
+                    direction=direction,
+                )
+                for item in object_
+            }
+        elif (
+            (
+                typing_extensions.get_origin(clean_type) == typing.List
+                or typing_extensions.get_origin(clean_type) == list
+                or clean_type == typing.List
+            )
+            and isinstance(object_, typing.List)
+        ) or (
+            (
+                typing_extensions.get_origin(clean_type) == typing.Sequence
+                or typing_extensions.get_origin(clean_type) == collections.abc.Sequence
+                or clean_type == typing.Sequence
+            )
+            and isinstance(object_, typing.Sequence)
+        ):
+            inner_type = typing_extensions.get_args(clean_type)[0]
+            return [
+                convert_and_respect_annotation_metadata(
+                    object_=item,
+                    annotation=annotation,
+                    inner_type=inner_type,
+                    direction=direction,
+                )
+                for item in object_
+            ]
+
+    if typing_extensions.get_origin(clean_type) == typing.Union:
+        # We should be able to ~relatively~ safely try to convert keys against all
+        # member types in the union, the edge case here is if one member aliases a field
+        # of the same name to a different name from another member
+        # Or if another member aliases a field of the same name that another member does not.
+        for member in typing_extensions.get_args(clean_type):
+            object_ = convert_and_respect_annotation_metadata(
+                object_=object_,
+                annotation=annotation,
+                inner_type=member,
+                direction=direction,
+            )
+        return object_
+
+    annotated_type = _get_annotation(annotation)
+    if annotated_type is None:
+        return object_
+
+    # If the object is not a TypedDict, a Union, or other container (list, set, sequence, etc.)
+    # Then we can safely call it on the recursive conversion.
+    return object_
+
+
+def _convert_mapping(
+    object_: typing.Mapping[str, object],
+    expected_type: typing.Any,
+    direction: typing.Literal["read", "write"],
+) -> typing.Mapping[str, object]:
+    converted_object: typing.Dict[str, object] = {}
+    annotations = _get_cached_type_hints(expected_type)
+    aliases_to_field_names = _get_alias_to_field_name(annotations)
+    for key, value in object_.items():
+        if direction == "read" and key in aliases_to_field_names:
+            dealiased_key = aliases_to_field_names.get(key)
+            if dealiased_key is not None:
+                type_ = annotations.get(dealiased_key)
+        else:
+            type_ = annotations.get(key)
+        # Note you can't get the annotation by the field name if you're in read mode, so you must check the aliases map
+        #
+        # So this is effectively saying if we're in write mode, and we don't have a type, or if we're in read mode and we don't have an alias
+        # then we can just pass the value through as is
+        if type_ is None:
+            converted_object[key] = value
+        elif direction == "read" and key not in aliases_to_field_names:
+            converted_object[key] = convert_and_respect_annotation_metadata(
+                object_=value, annotation=type_, direction=direction
+            )
+        else:
+            converted_object[_alias_key(key, type_, direction, aliases_to_field_names)] = (
+                convert_and_respect_annotation_metadata(object_=value, annotation=type_, direction=direction)
+            )
+    return converted_object
+
+
+def _get_annotation(type_: typing.Any) -> typing.Optional[typing.Any]:
+    maybe_annotated_type = typing_extensions.get_origin(type_)
+    if maybe_annotated_type is None:
+        return None
+
+    if maybe_annotated_type == typing_extensions.NotRequired:
+        type_ = typing_extensions.get_args(type_)[0]
+        maybe_annotated_type = typing_extensions.get_origin(type_)
+
+    if maybe_annotated_type == typing_extensions.Annotated:
+        return type_
+
+    return None
+
+
+def _remove_annotations(type_: typing.Any) -> typing.Any:
+    maybe_annotated_type = typing_extensions.get_origin(type_)
+    if maybe_annotated_type is None:
+        return type_
+
+    if maybe_annotated_type == typing_extensions.NotRequired:
+        return _remove_annotations(typing_extensions.get_args(type_)[0])
+
+    if maybe_annotated_type == typing_extensions.Annotated:
+        return _remove_annotations(typing_extensions.get_args(type_)[0])
+
+    return type_
+
+
+def get_alias_to_field_mapping(type_: typing.Any) -> typing.Dict[str, str]:
+    annotations = _get_cached_type_hints(type_)
+    return _get_alias_to_field_name(annotations)
+
+
+def get_field_to_alias_mapping(type_: typing.Any) -> typing.Dict[str, str]:
+    annotations = _get_cached_type_hints(type_)
+    return _get_field_to_alias_name(annotations)
+
+
+def _get_alias_to_field_name(
+    field_to_hint: typing.Dict[str, typing.Any],
+) -> typing.Dict[str, str]:
+    aliases = {}
+    for field, hint in field_to_hint.items():
+        maybe_alias = _get_alias_from_type(hint)
+        if maybe_alias is not None:
+            aliases[maybe_alias] = field
+    return aliases
+
+
+def _get_field_to_alias_name(
+    field_to_hint: typing.Dict[str, typing.Any],
+) -> typing.Dict[str, str]:
+    aliases = {}
+    for field, hint in field_to_hint.items():
+        maybe_alias = _get_alias_from_type(hint)
+        if maybe_alias is not None:
+            aliases[field] = maybe_alias
+    return aliases
+
+
+def _get_alias_from_type(type_: typing.Any) -> typing.Optional[str]:
+    maybe_annotated_type = _get_annotation(type_)
+
+    if maybe_annotated_type is not None:
+        # The actual annotations are 1 onward, the first is the annotated type
+        annotations = typing_extensions.get_args(maybe_annotated_type)[1:]
+
+        for annotation in annotations:
+            if isinstance(annotation, FieldMetadata) and annotation.alias is not None:
+                return annotation.alias
+    return None
+
+
+def _alias_key(
+    key: str,
+    type_: typing.Any,
+    direction: typing.Literal["read", "write"],
+    aliases_to_field_names: typing.Dict[str, str],
+) -> str:
+    if direction == "read":
+        return aliases_to_field_names.get(key, key)
+    return _get_alias_from_type(type_=type_) or key

autoassembler/environment.py

@@ -0,0 +1,7 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import enum
+
+
+class AutoAssemblerEnvironment(enum.Enum):
+    PRODUCTION = "https://app.autoassembler.com"

autoassembler/errors/__init__.py

@@ -0,0 +1,56 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
+import typing
+from importlib import import_module
+
+if typing.TYPE_CHECKING:
+    from .bad_request_error import BadRequestError
+    from .conflict_error import ConflictError
+    from .forbidden_error import ForbiddenError
+    from .internal_server_error import InternalServerError
+    from .not_found_error import NotFoundError
+    from .unauthorized_error import UnauthorizedError
+    from .unprocessable_entity_error import UnprocessableEntityError
+_dynamic_imports: typing.Dict[str, str] = {
+    "BadRequestError": ".bad_request_error",
+    "ConflictError": ".conflict_error",
+    "ForbiddenError": ".forbidden_error",
+    "InternalServerError": ".internal_server_error",
+    "NotFoundError": ".not_found_error",
+    "UnauthorizedError": ".unauthorized_error",
+    "UnprocessableEntityError": ".unprocessable_entity_error",
+}
+
+
+def __getattr__(attr_name: str) -> typing.Any:
+    module_name = _dynamic_imports.get(attr_name)
+    if module_name is None:
+        raise AttributeError(f"No {attr_name} found in _dynamic_imports for module name -> {__name__}")
+    try:
+        module = import_module(module_name, __package__)
+        if module_name == f".{attr_name}":
+            return module
+        else:
+            return getattr(module, attr_name)
+    except ImportError as e:
+        raise ImportError(f"Failed to import {attr_name} from {module_name}: {e}") from e
+    except AttributeError as e:
+        raise AttributeError(f"Failed to get {attr_name} from {module_name}: {e}") from e
+
+
+def __dir__():
+    lazy_attrs = list(_dynamic_imports.keys())
+    return sorted(lazy_attrs)
+
+
+__all__ = [
+    "BadRequestError",
+    "ConflictError",
+    "ForbiddenError",
+    "InternalServerError",
+    "NotFoundError",
+    "UnauthorizedError",
+    "UnprocessableEntityError",
+]

autoassembler/errors/bad_request_error.py

@@ -0,0 +1,10 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.api_error import ApiError
+
+
+class BadRequestError(ApiError):
+    def __init__(self, body: typing.Any, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=400, headers=headers, body=body)

autoassembler/errors/conflict_error.py

@@ -0,0 +1,10 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.api_error import ApiError
+
+
+class ConflictError(ApiError):
+    def __init__(self, body: typing.Any, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=409, headers=headers, body=body)

autoassembler/errors/forbidden_error.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.api_error import ApiError
+from ..types.error_response import ErrorResponse
+
+
+class ForbiddenError(ApiError):
+    def __init__(self, body: ErrorResponse, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=403, headers=headers, body=body)

autoassembler/errors/internal_server_error.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.api_error import ApiError
+from ..types.o_auth_error_response import OAuthErrorResponse
+
+
+class InternalServerError(ApiError):
+    def __init__(self, body: OAuthErrorResponse, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=500, headers=headers, body=body)

autoassembler/errors/not_found_error.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.api_error import ApiError
+from ..types.error_response import ErrorResponse
+
+
+class NotFoundError(ApiError):
+    def __init__(self, body: ErrorResponse, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=404, headers=headers, body=body)

autoassembler/errors/unauthorized_error.py

@@ -0,0 +1,10 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.api_error import ApiError
+
+
+class UnauthorizedError(ApiError):
+    def __init__(self, body: typing.Any, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=401, headers=headers, body=body)

autoassembler/errors/unprocessable_entity_error.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.api_error import ApiError
+from ..types.error_response import ErrorResponse
+
+
+class UnprocessableEntityError(ApiError):
+    def __init__(self, body: ErrorResponse, headers: typing.Optional[typing.Dict[str, str]] = None):
+        super().__init__(status_code=422, headers=headers, body=body)

autoassembler/operation.py

@@ -0,0 +1,196 @@
+"""Handles for awaiting the server's long-running operations.
+
+Custom (hand-written) code — NOT generated by Fern. Protected via `.fernignore`.
+
+An endpoint whose work continues after it answers returns an operation
+(`autoassembler.types.Operation`, shaped after Google's
+[AIP-151](https://google.aip.dev/151)): ``done`` once the server has recorded the outcome,
+then exactly one of ``response`` or ``error``. That model is a snapshot of one GET.
+`Operation` wraps it, like ``google.api_core.operation.Operation`` wraps the
+``google.longrunning.Operation`` message: `done` fetches the latest state while the
+operation runs, and `result` short-polls with exponential backoff until it is done, then
+returns the response (or what ``resolve`` makes of it) or raises `OperationFailed`.
+"""
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any, cast
+
+from .types.operation import Operation as OperationResource
+from .types.operation_error import OperationError
+
+# Backoff between polls in `result`: seconds before the first re-poll, its growth per poll, its cap.
+POLL_INTERVAL = 1.0
+POLL_MULTIPLIER = 1.5
+MAX_POLL_INTERVAL = 20.0
+
+
+class OperationFailed(Exception):
+    """The operation finished with an error.
+
+    ``code`` is its ``google.rpc.Code`` (e.g. 1 cancelled, 13 internal, 14 unavailable) and
+    ``operation`` the finished operation.
+    """
+
+    def __init__(self, operation: OperationResource):
+        error = operation.error or OperationError(code=2, message="finished without a response")
+        super().__init__(f"{operation.name} failed ({error.code}): {error.message}")
+        self.operation = operation
+        self.code = error.code
+        self.message = error.message
+
+
+class OperationTimeout(TimeoutError):
+    """The operation did not finish within the time `result` was given; it may still finish."""
+
+    def __init__(self, operation: OperationResource, timeout: float):
+        super().__init__(f"{operation.name} did not finish within {timeout}s")
+        self.operation = operation
+
+
+def operation_id(name: str) -> str:
+    """The id `get_operation` takes: the part of ``name`` after ``operations/``."""
+    return name.removeprefix("operations/")
+
+
+class _Backoff:
+    """Seconds between polls: growing by `POLL_MULTIPLIER` up to a cap, and within the deadline."""
+
+    def __init__(self, poll_interval: float, max_poll_interval: float, timeout: float | None):
+        self._next = poll_interval
+        self._max = max_poll_interval
+        self._deadline = None if timeout is None else time.monotonic() + timeout
+
+    def expired(self) -> bool:
+        return self._deadline is not None and time.monotonic() >= self._deadline
+
+    def delay(self) -> float:
+        delay = min(self._next, self._max)
+        if self._deadline is not None:
+            delay = max(0.0, min(delay, self._deadline - time.monotonic()))
+        self._next *= POLL_MULTIPLIER
+        return delay
+
+
+class Operation[T]:
+    """A long-running operation the server is running, and its eventual result.
+
+    Args:
+        operation: The operation as last fetched, e.g. from the endpoint's 202.
+        refresh: Fetches the operation's current state.
+        resolve: Maps the finished operation to the result; defaults to its ``response``.
+    """
+
+    def __init__(
+        self,
+        operation: OperationResource,
+        *,
+        refresh: Callable[[], OperationResource],
+        resolve: Callable[[OperationResource], T] | None = None,
+    ):
+        self._operation = operation
+        self._refresh = refresh
+        self._resolve = resolve
+
+    @property
+    def name(self) -> str:
+        return self._operation.name
+
+    @property
+    def operation(self) -> OperationResource:
+        """The operation as last fetched; `done` fetches it again while it runs."""
+        return self._operation
+
+    @property
+    def metadata(self) -> Any:
+        return self._operation.metadata
+
+    def done(self) -> bool:
+        """Whether the operation has finished; fetches its current state unless it already had."""
+        if not self._operation.done:
+            self._operation = self._refresh()
+        return self._operation.done
+
+    def result(
+        self,
+        *,
+        timeout: float | None = None,
+        poll_interval: float = POLL_INTERVAL,
+        max_poll_interval: float = MAX_POLL_INTERVAL,
+    ) -> T:
+        """Wait until the operation finishes and return its result.
+
+        Polls with exponential backoff from ``poll_interval`` up to ``max_poll_interval``
+        seconds. Raises `OperationFailed` if it finished with an error and `OperationTimeout`
+        if it is still running after ``timeout`` seconds (``None`` waits indefinitely).
+        """
+        backoff = _Backoff(poll_interval, max_poll_interval, timeout)
+        while not self.done():
+            if backoff.expired():
+                raise OperationTimeout(self._operation, timeout or 0.0)
+            time.sleep(backoff.delay())
+        if self._operation.error is not None or self._operation.response is None:
+            raise OperationFailed(self._operation)
+        if self._resolve is not None:
+            return self._resolve(self._operation)
+        return cast(T, self._operation.response)
+
+    def __repr__(self) -> str:
+        return f"Operation({self.name!r}, done={self._operation.done})"
+
+
+class AsyncOperation[T]:
+    """The async mirror of `Operation`: `done` and `result` are coroutines."""
+
+    def __init__(
+        self,
+        operation: OperationResource,
+        *,
+        refresh: Callable[[], Awaitable[OperationResource]],
+        resolve: Callable[[OperationResource], Awaitable[T]] | None = None,
+    ):
+        self._operation = operation
+        self._refresh = refresh
+        self._resolve = resolve
+
+    @property
+    def name(self) -> str:
+        return self._operation.name
+
+    @property
+    def operation(self) -> OperationResource:
+        """The operation as last fetched; `done` fetches it again while it runs."""
+        return self._operation
+
+    @property
+    def metadata(self) -> Any:
+        return self._operation.metadata
+
+    async def done(self) -> bool:
+        """Whether the operation has finished; fetches its current state unless it already had."""
+        if not self._operation.done:
+            self._operation = await self._refresh()
+        return self._operation.done
+
+    async def result(
+        self,
+        *,
+        timeout: float | None = None,
+        poll_interval: float = POLL_INTERVAL,
+        max_poll_interval: float = MAX_POLL_INTERVAL,
+    ) -> T:
+        """Wait until the operation finishes and return its result; see `Operation.result`."""
+        backoff = _Backoff(poll_interval, max_poll_interval, timeout)
+        while not await self.done():
+            if backoff.expired():
+                raise OperationTimeout(self._operation, timeout or 0.0)
+            await asyncio.sleep(backoff.delay())
+        if self._operation.error is not None or self._operation.response is None:
+            raise OperationFailed(self._operation)
+        if self._resolve is not None:
+            return await self._resolve(self._operation)
+        return cast(T, self._operation.response)
+
+    def __repr__(self) -> str:
+        return f"AsyncOperation({self.name!r}, done={self._operation.done})"