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

Storage driver backed by Amazon S3 (or S3-compatible services).

Uses the official AWS SDK for Python (boto3), which is an optional dependency: it is not installed with the framework. Install it before using this driver:

uv add 'orionis[s3]'

Cancellation waits for active SDK work before resources are released. The SDK is imported lazily on first operation, and every blocking call runs on a worker thread via asyncio.to_thread so the event loop stays responsive. Directories are virtual: prefixes are inferred from object keys, and explicit directories are stored as zero-byte path/ marker objects.

Method __aclFor Map a visibility level onto an S3 canned ACL.
Method __client Return the boto3 S3 client, bootstrapping it on first use.
Method __headSync Fetch object metadata or raise when the object is absent.
Method __init__ Initialize the driver from an S3 disk configuration entity.
Method __isMissing Check whether an SDK error denotes a missing object.
Method __listKeysSync List every object key under prefix.
Method __missing Build the framework exception for a missing object.
Method __putArgs Build the optional arguments for an object upload.
Method __seedStream Seed buffer with the current object content for a stream.
Method __urlFor Compose the public URL of an object without SDK involvement.
Method __visibilitySync Resolve the object visibility from its ACL grants.
Async Method copy Copy the object at source to target server-side.
Async Method createDirectory Create a zero-byte directory marker at path.
Async Method delete Delete the object at path.
Async Method deleteDirectory Recursively delete every object under path.
Async Method directories List the directory prefixes contained under path.
Async Method directoryExists Check whether any object exists under path.
Async Method download Download the object at path to the local filesystem.
Async Method exists Check whether an object exists at path.
Async Method files List the object keys that represent files under path.
Async Method hash Compute the content hash of the object at path.
Async Method info Collect a metadata snapshot for the object at path.
Async Method lastModified Return the last-modification timestamp of the object at path.
Async Method mimeType Return the MIME type of the object at path.
Async Method move Move the object at source to target.
Method open Open an asynchronous binary stream for the object at path.
Async Method read Read the full contents of the object at path.
Async Method readStream Stream the contents of the object at path in chunks.
Async Method setVisibility Change the visibility of the object at path.
Async Method size Return the size in bytes of the object at path.
Async Method temporaryUrl Build a presigned URL for the object at path.
Async Method url Build the public URL for the object at path.
Async Method visibility Return the visibility of the object at path.
Async Method write Write contents to path, replacing any existing object.
Async Method writeStream Write the chunks produced by stream to path.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _base_url Base URL used when constructing public resource URLs.
Instance Variable _bucket Cloud-storage bucket containing the driver resources.
Instance Variable _client Client used to communicate with the configured backend.
Instance Variable _client_error Client error supplied through Exception.
Instance Variable _client_lock Serialize lazy SDK initialization across worker threads.
Instance Variable _endpoint Configured endpoint used to contact the storage service.
Instance Variable _key Key produced by str.
Instance Variable _region Region produced by str.
Instance Variable _secret Secret produced by str.
Instance Variable _use_path_style Use path style produced by bool.

Inherited from IStorageDriver:

Method absolutePath Return the absolute filesystem path of the file at path.
Method relativePath Return the filesystem path relative to the application base path.
def __aclFor(self: Self, visibility: str) -> str: (source)

Map a visibility level onto an S3 canned ACL.

Parameters
visibility:strVisibility level ('public' or 'private').
Returns
strCanned ACL name.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf visibility is not a supported level.
def __client(self: Self) -> Any: (source)

Return the boto3 S3 client, bootstrapping it on first use.

Returns
typing.AnyConfigured boto3 S3 client.
Raises
orionis.storage.exceptions.MissingStorageDependencyExceptionIf boto3 is not installed.
def __headSync(self: Self, normalized: str) -> dict: (source)

Fetch object metadata or raise when the object is absent.

Parameters
normalized:strCanonical root-relative file path.
Returns
dictRaw head_object response.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
def __init__(self: Self, config: object): (source)

Initialize the driver from an S3 disk configuration entity.

No SDK import or network activity happens here; the client is bootstrapped lazily on first use.

Parameters
config:objectDisk configuration exposing bucket, region, key, secret, url, endpoint, and use_path_style_endpoint.
Returns
NoneNo return value.
def __isMissing(self: Self, exc: Exception) -> bool: (source)

Check whether an SDK error denotes a missing object.

Parameters
exc:ExceptionException raised by the boto3 client.
Returns
boolTrue when the error code maps to a 404 condition.
def __listKeysSync(self: Self, prefix: str) -> list[str]: (source)

List every object key under prefix.

Parameters
prefix:strKey prefix to filter by; empty string lists the bucket.
Returns
list[str]All matching object keys, including directory markers.
def __missing(self: Self, normalized: str) -> StorageFileNotFoundException: (source)

Build the framework exception for a missing object.

Parameters
normalized:strCanonical root-relative file path.
Returns
orionis.storage.exceptions.StorageFileNotFoundExceptionException instance ready to be raised.
def __putArgs(self: Self, normalized: str, visibility: str | None) -> dict[str, str]: (source)

Build the optional arguments for an object upload.

Parameters
normalized:strCanonical root-relative file path.
visibility:str | NoneVisibility to apply, or None to omit the ACL.
Returns
dict[str, str]Extra arguments with ContentType and optional ACL.
def __seedStream(self: Self, buffer: BinaryIO, normalized: str, mode: str): (source)

Seed buffer with the current object content for a stream.

Downloads the object into the buffer and positions the cursor according to mode. Missing objects are tolerated for append modes and rejected for read modes.

Parameters
buffer:typing.BinaryIOSpooled buffer backing the stream.
normalized:strCanonical root-relative file path.
mode:strBinary mode requested by the caller.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist and mode requires it.
def __urlFor(self: Self, normalized: str) -> str: (source)

Compose the public URL of an object without SDK involvement.

Parameters
normalized:strCanonical root-relative file path.
Returns
strPublic URL derived from the configured base URL, custom endpoint, or the canonical virtual-host address.
def __visibilitySync(self: Self, normalized: str) -> str: (source)

Resolve the object visibility from its ACL grants.

Parameters
normalized:strCanonical root-relative file path.
Returns
str'public' when anonymous users hold a read grant, otherwise 'private'.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def copy(self: Self, source: str, target: str): (source)

Copy the object at source to target server-side.

Parameters
source:strRoot-relative path of the existing object.
target:strRoot-relative destination path.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the source object does not exist.
async def createDirectory(self: Self, path: str): (source)

Create a zero-byte directory marker at path.

Parameters
path:strRoot-relative directory path.
Returns
NoneNo return value.
async def delete(self: Self, path: str) -> bool: (source)

Delete the object at path.

Parameters
path:strRoot-relative file path.
Returns
boolTrue if the object existed and was removed.
async def deleteDirectory(self: Self, path: str) -> bool: (source)

Recursively delete every object under path.

Parameters
path:strRoot-relative directory path. The empty string clears the whole bucket prefix space.
Returns
boolTrue if at least one object was removed.
Raises
botocore.exceptions.ClientErrorIf a batch reports a per-object failure. The exception retains the complete response, including successful deletions and errors.
async def directories(self: Self, path: str = '', *, recursive: bool = False) -> list[str]: (source)

List the directory prefixes contained under path.

Parameters
path:strRoot-relative directory path. Empty string for the root.
recursive:boolWhen True, include all nested prefixes.
Returns
list[str]Sorted root-relative directory paths.
async def directoryExists(self: Self, path: str) -> bool: (source)

Check whether any object exists under path.

Parameters
path:strRoot-relative directory path. The empty string denotes the disk root.
Returns
boolTrue if the prefix contains at least one object.
async def download(self: Self, path: str, destination: str | Path) -> Path: (source)

Download the object at path to the local filesystem.

Parameters
path:strRoot-relative file path on the disk.
destination:str | pathlib.PathLocal target. When it points to an existing directory the file keeps its original name inside that directory.
Returns
pathlib.PathAbsolute local path of the downloaded file.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def exists(self: Self, path: str) -> bool: (source)

Check whether an object exists at path.

Parameters
path:strRoot-relative file path.
Returns
boolTrue if an object exists at the given key.
async def files(self: Self, path: str = '', *, recursive: bool = False) -> list[str]: (source)

List the object keys that represent files under path.

Parameters
path:strRoot-relative directory path. Empty string for the root.
recursive:boolWhen True, include files from all nested prefixes.
Returns
list[str]Sorted root-relative file paths.
async def hash(self: Self, path: str, algorithm: str = 'sha256') -> str: (source)

Compute the content hash of the object at path.

The object is streamed in chunks, so large files never load fully into memory.

Parameters
path:strRoot-relative file path.
algorithm:strFixed-length digest algorithm accepted by hashlib.new.
Returns
strHexadecimal digest of the object contents.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf algorithm is unavailable or requires an explicit digest length.
async def info(self: Self, path: str) -> FileInfo: (source)

Collect a metadata snapshot for the object at path.

The snapshot is built from object metadata only; the checksum field is None because computing it would require a full download (use hash instead).

Parameters
path:strRoot-relative file path.
Returns
orionis.storage.entities.FileInfoImmutable entity with size, MIME type, timestamps, ETag, visibility, and URL.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def lastModified(self: Self, path: str) -> datetime: (source)

Return the last-modification timestamp of the object at path.

Parameters
path:strRoot-relative file path.
Returns
datetime.datetimeTimezone-aware modification timestamp.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def mimeType(self: Self, path: str) -> str | None: (source)

Return the MIME type of the object at path.

Prefers the Content-Type stored in S3 and falls back to a guess based on the file extension.

Parameters
path:strRoot-relative file path.
Returns
str | NoneMIME type, or None when it cannot be determined.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def move(self: Self, source: str, target: str): (source)

Move the object at source to target.

Implemented as a server-side copy followed by a delete of the source object.

Parameters
source:strRoot-relative path of the existing object.
target:strRoot-relative destination path.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the source object does not exist.
def open(self: Self, path: str, mode: str = 'rb') -> AsyncStream: (source)

Open an asynchronous binary stream for the object at path.

Read-oriented modes download the object into a spooled temporary buffer; writable modes upload the buffered content back to S3 when the stream is closed.

Parameters
path:strRoot-relative file path.
mode:strBinary mode: 'rb', 'wb', 'ab', 'rb+', 'wb+', or 'ab+'.
Returns
orionis.storage.AsyncStreamLazily opened stream; use it as an async context manager.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf mode is not a supported binary mode.
async def read(self: Self, path: str) -> bytes: (source)

Read the full contents of the object at path.

Parameters
path:strRoot-relative file path.
Returns
bytesComplete object contents.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def readStream(self: Self, path: str, chunk_size: int = _CHUNK_SIZE) -> AsyncIterator[bytes]: (source)

Stream the contents of the object at path in chunks.

Parameters
path:strRoot-relative file path.
chunk_size:intMaximum number of bytes per yielded chunk.
Yields
bytesConsecutive chunks of the object contents.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def setVisibility(self: Self, path: str, visibility: str): (source)

Change the visibility of the object at path.

Parameters
path:strRoot-relative file path.
visibility:strTarget visibility ('public' or 'private').
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf visibility is not a supported level.
async def size(self: Self, path: str) -> int: (source)

Return the size in bytes of the object at path.

Parameters
path:strRoot-relative file path.
Returns
intObject size in bytes.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def temporaryUrl(self: Self, path: str, expires_in: int) -> str: (source)

Build a presigned URL for the object at path.

Parameters
path:strRoot-relative file path.
expires_in:intLifetime of the URL in seconds.
Returns
strPresigned GET URL valid for expires_in seconds.
Raises
orionis.storage.exceptions.MissingStorageDependencyExceptionIf boto3 is not installed.
async def url(self: Self, path: str) -> str: (source)

Build the public URL for the object at path.

Parameters
path:strRoot-relative file path.
Returns
strURL derived from the configured base URL, custom endpoint, or the canonical virtual-host address.
async def visibility(self: Self, path: str) -> str: (source)

Return the visibility of the object at path.

Parameters
path:strRoot-relative file path.
Returns
str'public' or 'private' based on the object ACL.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
async def write(self: Self, path: str, contents: bytes | str, visibility: str | None = None): (source)

Write contents to path, replacing any existing object.

Parameters
path:strRoot-relative file path.
contents:bytes | strData to persist. Strings are encoded as UTF-8.
visibility:str | NoneVisibility to apply, or None for the bucket default.
Returns
NoneNo return value.
async def writeStream(self: Self, path: str, stream: AsyncIterable[bytes], visibility: str | None = None): (source)

Write the chunks produced by stream to path.

The payload is buffered into a spooled temporary file (spilling to disk past 8 MiB) and uploaded with the SDK's managed transfer, which switches to multipart uploads for large objects.

Parameters
path:strRoot-relative file path.
stream:collections.abc.AsyncIterable[bytes]Asynchronous byte-chunk producer.
visibility:str | NoneVisibility to apply, or None for the bucket default.
Returns
NoneNo return value.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_base_url: str | None = (source)

Base URL used when constructing public resource URLs.

Cloud-storage bucket containing the driver resources.

_client: Any = (source)

Client used to communicate with the configured backend.

_client_error: type[Exception] = (source)

Client error supplied through Exception.

_client_lock = (source)

Serialize lazy SDK initialization across worker threads.

_endpoint: str | None = (source)

Configured endpoint used to contact the storage service.

Key produced by str.

Region produced by str.

Secret produced by str.

_use_path_style: bool = (source)

Use path style produced by bool.