Source code for signal_dataset.storage.staging.contracts

"""The contract for making a stored shard openable by a native reader.

The ArrayRecord binding takes a *path*, not a file object, and its compiled
driver table registers exactly one remote scheme, ``gs://``. So a shard held
anywhere else has to become a path before a record can be read out of it.

A staging area is that step. Which implementation serves a scheme decides the
cost model: yielding the URI untouched costs nothing, while materializing the
object trades a download for the ability to read at all.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from contextlib import AbstractContextManager




class ShardStagingArea(ABC):
    """Makes a stored shard openable by a path-only indexed reader."""



    @abstractmethod
    def stage(
        self, uri: str, *, generation: int | None = None
    ) -> AbstractContextManager[str]:
        """Return a context manager yielding a path the reader may open.

        The path is valid only while the context is active. On exit, including
        on an exception, the implementation releases everything it acquired for
        this call.
        """