hubvault.optional

Optional-dependency helpers for hubvault.

This module centralizes delayed imports for optional runtime integrations such as the embedded HTTP server and remote HTTP client. Callers may import these helpers in the base installation without triggering immediate import failures; missing extras are reported only when the optional feature is actually used.

The module contains:

MissingOptionalDependencyError

class hubvault.optional.MissingOptionalDependencyError(*, extra: str, feature: str, package: str = 'hubvault', missing_name: str | None = None)[source]

Raised when an optional extra is required at runtime.

Parameters:

  • extra (str) – Extra name that satisfies the missing dependency

  • feature (str) – User-facing feature description that needs the extra

  • package (str) – Package name used in the install hint, defaults to "hubvault"

  • missing_name (Optional[str]) – Optional missing module name reported by Python import machinery

Example:

>>> err = MissingOptionalDependencyError(
...     extra="api",
...     feature="embedded server",
...     missing_name="fastapi",
... )
>>> "hubvault[api]" in str(err)
True
__init__(*, extra: str, feature: str, package: str = 'hubvault', missing_name: str | None = None) → None[source]

Build one delayed-import failure with an actionable install message.

Parameters:

  • extra (str) – Extra name that satisfies the missing dependency

  • feature (str) – User-facing feature description that needs the extra

  • package (str) – Package name used in the install hint

  • missing_name (Optional[str]) – Optional missing module name reported by Python import machinery

Returns:

None.

Return type:

None

import_optional_dependency

hubvault.optional.import_optional_dependency(module_name: str, *, extra: str, feature: str, package: str = 'hubvault', missing_names: Iterable[str] | None = None)[source]

Import one optional dependency with a user-facing install hint.

Parameters:

  • module_name (str) – Fully qualified module name to import

  • extra (str) – Extra name that satisfies the missing dependency

  • feature (str) – User-facing feature description that needs the dependency

  • package (str) – Package name used in the install hint, defaults to "hubvault"

  • missing_names (Optional[Iterable[str]]) – Additional module names that should map to the same install hint

Returns:

The imported module object

Return type:

module

Raises:

  • MissingOptionalDependencyError – Raised when the requested optional dependency or one of its accepted transitive imports is missing.

  • ModuleNotFoundError – Raised when an unrelated nested import fails.

Example:

>>> json_module = import_optional_dependency(
...     "json",
...     extra="api",
...     feature="example loader",
... )
>>> json_module.dumps({"ok": True})
'{"ok": true}'