Skip to content

compatibility#

zen_api_utils.compatibility #

Feature-scoped diagnostics for generated client and ZEN server capabilities.

Classes:

Functions:

  • api_capabilities –

    Guard API imports or a focused RPC call without masking unrelated errors.

  • api_operation –

    Apply capability diagnostics to an async utility operation.

ZenApiCompatibilityError #

ZenApiCompatibilityError(feature: str, detail: str)

Bases: RuntimeError

A required generated API capability or server RPC is unavailable.

Attributes:

  • feature (str) –

    Utility feature that could not be used.

  • detail (str) –

    Missing capability or unsupported server RPC.

api_capabilities #

api_capabilities(feature: str, target: object | None = None, *, members: tuple[str, ...] = (), methods: tuple[str, ...] = ()) -> Iterator[None]

Guard API imports or a focused RPC call without masking unrelated errors.

Parameters:

  • feature (str) –

    User-facing name of the utility feature.

  • target (object | None, default: None ) –

    Client, message, or generated type to inspect.

  • members (tuple[str, ...], default: () ) –

    Required attributes or dataclass fields.

  • methods (tuple[str, ...], default: () ) –

    Required callable client methods.

Raises:

  • ZenApiCompatibilityError –

    An API import, required capability, or server RPC is unavailable. Import and RPC failures retain their cause.

  • ValueError –

    Member or method checks were requested without a target.

Notes

This checks presence, not wire or behavioral compatibility. Other import errors, RPC statuses, and programming errors propagate unchanged.

api_operation #

api_operation(feature: str, target: object | None = None, *, members: tuple[str, ...] = (), methods: tuple[str, ...] = ()) -> Callable[[Callable[Parameters, Awaitable[Result]]], Callable[Parameters, Awaitable[Result]]]

Apply capability diagnostics to an async utility operation.

Parameters:

  • feature (str) –

    User-facing name of the utility operation.

  • target (object | None, default: None ) –

    Generated type to check before calling the function.

  • members (tuple[str, ...], default: () ) –

    Required attributes or dataclass fields.

  • methods (tuple[str, ...], default: () ) –

    Required callable client methods.

Returns:

  • Callable ( Callable[[Callable[Parameters, Awaitable[Result]]], Callable[Parameters, Awaitable[Result]]] ) –

    Decorator retaining the function's signature and return value.

Notes

Errors deliberately handled inside the function retain their existing fallback behavior. Cancellation and unrelated exceptions propagate.