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 AsyncStream(IStorageStream): (source)
Constructor: AsyncStream(opener, on_close)
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 | __ensure |
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 |
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. |
Open the underlying handle and return the stream.
| Returns | |
orionis.storage.contracts.IStorageStream | The stream itself, ready for I/O operations. |
Self, exc_type: type[ BaseException] | None, exc: BaseException | None, traceback: TracebackType | None):
(source)
¶
Close the stream when leaving the async context.
| Parameters | |
exctype[BaseException] | None | Exception class raised inside the context, if any. |
exc:BaseException | None | Exception instance raised inside the context, if any. |
traceback:types.TracebackType | None | Traceback of the raised exception, if any. |
| Returns | |
None | No return value. |
Persist and close the handle without replacing an existing failure.
| Parameters | |
primary:BaseException | None | Failure already propagating from the owning operation or context. |
| Returns | |
None | No return value. |
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.BinaryIO | The open binary handle backing this stream. |
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. |
oncollections.abc.Callable[[typing.BinaryIO], None] | None | Optional callback executed with the open handle right before it is closed. |
| Returns | |
None | No return value. |
Self, size: int = 65536, *, buffer_size: int = READ_BUFFER_SIZE) -> AsyncIterator[ bytes]:
(source)
¶
Yield logical chunks with bounded batching of synchronous reads.
| Parameters | |
size:int | Maximum yielded bytes per chunk. |
bufferint | Read-ahead budget, at least one logical chunk. |
| Yields | |
bytes | Sequential content. The surrounding async context owns close; callers must not mix iteration with writes, seek or other reads. |
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 | |
None | No return value. |