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.

module documentation

Provide shared binary buffers, dependency loading and object-key helpers.

Class _ModeBuffer Enforce binary access modes while owning a buffered storage payload.
Function __getattr__ Resolve and cache a legacy driver helper name.
Function _close_failed_buffer Close an unpublished buffer without replacing its opening failure.
Function _directory_ancestors Yield every directory prefix implied by key down to base.
Function assert_binary_mode Validate a stream mode against the supported binary modes.
Function derive_directories Derive the directory paths implied by object keys under base.
Function filter_files Select the object keys that represent files under base.
Function import_driver_dependency Import an optional SDK module required by a storage driver.
Function resolve_download_target Resolve the local target path for a download operation.
Constant _ALLOWED_MODES Binary modes accepted by driver open() implementations.
Constant _LEGACY_EXPORTS Legacy exports definitions used by functions.
def __getattr__(name: str) -> object: (source)

Resolve and cache a legacy driver helper name.

Parameters
name:strAttribute requested from this module.
Returns
objectExisting helper function bound to the requested name.
Raises
AttributeErrorIf the requested name is not a compatibility export.
def _close_failed_buffer(buffer: BinaryIO, primary: BaseException): (source)

Close an unpublished buffer without replacing its opening failure.

Parameters
buffer:typing.BinaryIOOwned buffer that could not be returned to its caller.
primary:BaseExceptionOriginal failure raised while preparing the buffer.
Returns
NoneNo return value.
def _directory_ancestors(key: str, base: str) -> Iterator[str]: (source)

Yield every directory prefix implied by key down to base.

Markers (keys ending with /) name a directory directly, while file keys imply their parent chain.

Parameters
key:strObject key, relative to the disk root.
base:strCanonical directory path acting as the traversal floor.
Yields
strDirectory paths between key and base, exclusive.
def assert_binary_mode(mode: str): (source)

Validate a stream mode against the supported binary modes.

Parameters
mode:strMode requested by the caller.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf mode is not one of 'rb', 'wb', 'ab', 'rb+', 'wb+', or 'ab+'.
def derive_directories(keys: Iterable[str], base: str, *, recursive: bool) -> list[str]: (source)

Derive the directory paths implied by object keys under base.

Object stores have no physical directories: prefixes are inferred from the stored keys, and keys ending with / act as explicit directory markers.

Parameters
keys:collections.abc.Iterable[str]Object keys, relative to the disk root.
base:strCanonical directory path acting as the listing root. The empty string denotes the disk root.
recursive:boolWhen True, include all nested directories.
Returns
list[str]Sorted directory paths under base.
def filter_files(keys: Iterable[str], base: str, *, recursive: bool) -> list[str]: (source)

Select the object keys that represent files under base.

Keys ending with / are treated as directory markers and are always excluded.

Parameters
keys:collections.abc.Iterable[str]Object keys, relative to the disk root.
base:strCanonical directory path acting as the listing root. The empty string denotes the disk root.
recursive:boolWhen True, include files from all nested prefixes.
Returns
list[str]Sorted file keys under base.
def import_driver_dependency(module: str, package: str, extra: str) -> ModuleType: (source)

Import an optional SDK module required by a storage driver.

Cloud drivers rely on the official SDK of each platform, which is not installed with the framework. This helper performs the import lazily and converts an unavailable import into a descriptive storage exception with installation instructions.

Parameters
module:strDotted module path to import (e.g. 'boto3').
package:strPyPI package that provides the module (e.g. 'boto3').
extra:strOrionis extra that pulls the package (e.g. 's3'), used to suggest uv add 'orionis[extra]'.
Returns
types.ModuleTypeThe imported module.
Raises
orionis.storage.exceptions.MissingStorageDependencyExceptionIf the module cannot be imported; retain the original import failure.
def resolve_download_target(normalized: str, destination: str | Path) -> Path: (source)

Resolve the local target path for a download operation.

When destination points to an existing directory, the file keeps its original name inside that directory. Missing parent directories are created.

Parameters
normalized:strCanonical root-relative path of the remote file.
destination:str | pathlib.PathLocal target file or existing directory.
Returns
pathlib.PathLocal path where the file must be written.
_ALLOWED_MODES: frozenset[str] = (source)

Binary modes accepted by driver open() implementations.

Value
frozenset(set(['rb', 'wb', 'ab', 'rb+', 'wb+', 'ab+']))
_LEGACY_EXPORTS = (source)

Legacy exports definitions used by functions.

Value
{'importDriverDependency': import_driver_dependency,
 'assertBinaryMode': assert_binary_mode,
 'resolveDownloadTarget': resolve_download_target,
 'filterFiles': filter_files,
 'deriveDirectories': derive_directories}