Skip to content

hyperion.ports.storage

hyperion.ports.storage

Port: object storage abstraction.

StoragePort is the dependency-inversion seam between :class:Catalog-style callers and a concrete object store (S3, local filesystem, in-memory). It is a runtime_checkable :class:typing.Protocol -- adapters satisfy it structurally, no forced inheritance (see docs/ddd-refactor-plan.md F1 / Step 4).

Contract:

  • get / open / get_attributes raise :class:ObjectNotFoundError when the key is absent.
  • delete is idempotent -- deleting a missing key is a no-op, never an error.
  • iter_keys yields keys in the same namespace put accepts (adapters that add a storage-side prefix strip it back off).

ObjectNotFoundError

Bases: KeyError

Raised when a requested storage key does not exist.

Subclasses :class:KeyError so callers that already except KeyError (and the in-memory adapter's natural error) keep working.

ObjectAttributes dataclass 

ObjectAttributes(etag, size, last_modified)

Backend-agnostic metadata for a stored object.

StoragePort

Bases: Protocol

Abstraction over object storage backends.

put 

put(key, data)

Store data under key, overwriting any existing object.

Source code in hyperion/ports/storage.py 
48
49
50
def put(self, key: str, data: bytes | IO[bytes]) -> None:
    """Store ``data`` under ``key``, overwriting any existing object."""
    ...

put_async async 

put_async(key, data)

Asynchronously store data under key.

Source code in hyperion/ports/storage.py 
52
53
54
async def put_async(self, key: str, data: bytes | IO[bytes]) -> None:
    """Asynchronously store ``data`` under ``key``."""
    ...

get 

get(key)

Return the full object stored under key.

Raises:

Type Description
ObjectNotFoundError

if key does not exist.
Source code in hyperion/ports/storage.py 
56
57
58
59
60
61
62
def get(self, key: str) -> bytes:
    """Return the full object stored under ``key``.

    Raises:
        ObjectNotFoundError: if ``key`` does not exist.
    """
    ...

open 

open(key)

Open key for streaming binary reads.

Raises:

Type Description
ObjectNotFoundError

if key does not exist.
Source code in hyperion/ports/storage.py 
64
65
66
67
68
69
70
def open(self, key: str) -> AbstractContextManager[IO[bytes]]:
    """Open ``key`` for streaming binary reads.

    Raises:
        ObjectNotFoundError: if ``key`` does not exist.
    """
    ...

iter_keys 

iter_keys(prefix)

Yield every key whose name starts with prefix.

Source code in hyperion/ports/storage.py 
72
73
74
def iter_keys(self, prefix: str) -> Iterator[str]:
    """Yield every key whose name starts with ``prefix``."""
    ...

exists 

exists(key)

Return whether an object is stored under key.

Source code in hyperion/ports/storage.py 
76
77
78
def exists(self, key: str) -> bool:
    """Return whether an object is stored under ``key``."""
    ...

delete 

delete(key)

Delete key. Idempotent -- a missing key is not an error.

Source code in hyperion/ports/storage.py 
80
81
82
def delete(self, key: str) -> None:
    """Delete ``key``. Idempotent -- a missing key is not an error."""
    ...

get_attributes 

get_attributes(key)

Return :class:ObjectAttributes for key.

Raises:

Type Description
ObjectNotFoundError

if key does not exist.
Source code in hyperion/ports/storage.py 
84
85
86
87
88
89
90
def get_attributes(self, key: str) -> ObjectAttributes:
    """Return :class:`ObjectAttributes` for ``key``.

    Raises:
        ObjectNotFoundError: if ``key`` does not exist.
    """
    ...