Skip to content

Typing

obspec_utils.obspec.ReadableStore

Bases: Get, GetAsync, GetRange, GetRangeAsync, GetRanges, GetRangesAsync, Head, HeadAsync, Protocol

Full read interface for transparent store wrappers.

This protocol combines the obspec protocols needed for stores that support complete read operations. It's used by transparent proxy wrappers like CachingReadableStore, TracingReadableStore, and SplittingReadableStore.

The protocol includes:

Warning

It's recommended to define your own protocols. This protocol may change without warning.

obspec_utils.obspec.ReadableFile

Bases: Protocol

Protocol for read-only file-like objects.

This protocol defines the minimal interface needed to read from a file-like object, compatible with libraries that expect file handles (e.g., h5py, zarr).

The obspec_utils readers (BufferedStoreReader, EagerStoreReader, BlockStoreReader) all implement this protocol, allowing them to be used interchangeably wherever a ReadableFile is expected.

Warning

It's recommended to define your own protocols. This protocol may change without warning.

Examples:

Using as a type hint for configurable readers:

from typing import Callable
from obspec_utils.protocols import ReadableStore, ReadableFile
from obspec_utils.readers import BufferedStoreReader

# Type alias for reader factories
ReaderFactory = Callable[[ReadableStore, str], ReadableFile]

def read_hdf5(
    store: ReadableStore,
    path: str,
    reader_factory: ReaderFactory = BufferedStoreReader,
):
    reader = reader_factory(store, path)
    # reader implements ReadableFile protocol
    with h5py.File(reader, mode="r") as f:
        ...

Runtime checking:

from obspec_utils.protocols import ReadableFile
from obspec_utils.readers import BufferedStoreReader

reader = BufferedStoreReader(store, "file.nc")
assert isinstance(reader, ReadableFile)  # True

read 

read(size: int = -1) -> bytes

Read up to size bytes from the file.

Parameters:

  • size (int, default: -1 ) –

    Number of bytes to read. If -1, read until EOF.

Returns:

  • bytes –

    The data read from the file.

seek 

seek(offset: int, whence: int = 0) -> int

Move to a new file position.

Parameters:

  • offset (int) –

    Position offset.

  • whence (int, default: 0 ) –

    Reference point: 0=start (SEEK_SET), 1=current (SEEK_CUR), 2=end (SEEK_END).

Returns:

  • int –

    The new absolute position.

tell 

tell() -> int

Return the current file position.

Returns:

  • int –

    Current position in bytes from start of file.

obspec_utils.typing.Url module-attribute 

Url: TypeAlias = str

A URL string (e.g., 's3://bucket/path' or 'example.com/file').

obspec_utils.typing.Path module-attribute 

Path: TypeAlias = str

A path string within an object store.