ORIONIS API REFERENCE

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

class documentation

Asynchronous wrapper around a lazily opened binary handle.

The underlying handle is produced by opener on first use (or on __aenter__) and every blocking operation is executed on a worker thread, keeping the event loop responsive. Drivers may provide an on_close callback to persist buffered data before the handle is released.

Async Method __aenter__ Open the underlying handle and return the stream.
Async Method __aexit__ Close the stream when leaving the async context.
Async Method __close Persist and close the handle without replacing an existing failure.
Async Method __ensureHandle Open the underlying handle on first use and return it.
Method __init__ Initialize the stream with its handle factory.
Async Method chunks Yield logical chunks with bounded batching of synchronous reads.
Async Method close Flush pending data and release the underlying handle.
Async Method read Read up to size bytes from the stream.
Async Method seek Move the stream position to offset.
Async Method write Write data to the stream at the current position.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _handle Open stream handle used for asynchronous file operations.
Instance Variable _lock Lock protecting concurrent access to shared state.
Instance Variable _on_close Optional callback executed with the open handle right before it is closed.
Instance Variable _opener Zero-argument callable returning the binary handle. It is invoked lazily on a worker thread.
async def __aenter__(self: Self) -> IStorageStream: (source)

Open the underlying handle and return the stream.

Returns
orionis.storage.contracts.IStorageStreamThe stream itself, ready for I/O operations.
async def __aexit__(self: Self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: TracebackType | None): (source)

Close the stream when leaving the async context.

Parameters
exc_type:type[BaseException] | NoneException class raised inside the context, if any.
exc:BaseException | NoneException instance raised inside the context, if any.
traceback:types.TracebackType | NoneTraceback of the raised exception, if any.
Returns
NoneNo return value.
async def __close(self, primary: BaseException | None): (source)

Persist and close the handle without replacing an existing failure.

Parameters
primary:BaseException | NoneFailure already propagating from the owning operation or context.
Returns
NoneNo return value.
async def __ensureHandle(self: Self) -> BinaryIO: (source)

Open the underlying handle on first use and return it.

Notes

If cancellation races with opening, close the late handle and observe cleanup failures without replacing the caller's cancellation.

Returns
typing.BinaryIOThe open binary handle backing this stream.
def __init__(self: Self, opener: Callable[[], BinaryIO], on_close: Callable[[BinaryIO], None] | None = None): (source)

Initialize the stream with its handle factory.

Parameters
opener:collections.abc.Callable[[], typing.BinaryIO]Zero-argument callable returning the binary handle. It is invoked lazily on a worker thread.
on_close:collections.abc.Callable[[typing.BinaryIO], None] | NoneOptional callback executed with the open handle right before it is closed.
Returns
NoneNo return value.
async def chunks(self: Self, size: int = 65536, *, buffer_size: int = READ_BUFFER_SIZE) -> AsyncIterator[bytes]: (source)

Yield logical chunks with bounded batching of synchronous reads.

Parameters
size:intMaximum yielded bytes per chunk.
buffer_size:intRead-ahead budget, at least one logical chunk.
Yields
bytesSequential content. The surrounding async context owns close; callers must not mix iteration with writes, seek or other reads.
async def close(self: Self): (source)

Flush pending data and release the underlying handle.

Invokes the on_close callback (when provided) before closing the handle. Closing an unopened or already closed stream is a no-op. A failed close does not replace a persistence failure. Context manager exit also preserves its own body failure; explicit close propagates its cleanup failure regardless of a caller's handled error.

Returns
NoneNo return value.
async def read(self: Self, size: int = -1) -> bytes: (source)

Read up to size bytes from the stream.

Parameters
size:intMaximum number of bytes to read. -1 reads until EOF.
Returns
bytesBytes read from the current position; empty at EOF.
async def seek(self: Self, offset: int, whence: int = 0) -> int: (source)

Move the stream position to offset.

Parameters
offset:intTarget offset relative to whence.
whence:intAnchor point: 0 start, 1 current, 2 end.
Returns
intThe new absolute position within the stream.
async def write(self: Self, data: bytes) -> int: (source)

Write data to the stream at the current position.

Parameters
data:bytesRaw bytes to write.
Returns
intNumber of bytes written.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_handle: BinaryIO | None = (source)

Open stream handle used for asynchronous file operations.

Lock protecting concurrent access to shared state.

_on_close = (source)

Optional callback executed with the open handle right before it is closed.

Zero-argument callable returning the binary handle. It is invoked lazily on a worker thread.