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 the local filesystem.

Every path is resolved inside the configured root directory. Content and metadata I/O runs on worker threads via asyncio.to_thread, keeping the event loop responsive. Path accessors are synchronous and validate filesystem boundaries without requiring the file to exist. Visibility is mapped onto POSIX permission bits (0o644/0o600 for files), which degrades gracefully on platforms without a full POSIX mode implementation.

Preserve permission and device failures as their original I/O exceptions. Missing paths retain the normal missing-file or empty existence results.

Static Method __iterEntries Yield the direct children of the requested kind under base.
Static Method __tempPath Build a unique staging path for an atomic write.
Static Method __walkEntries Yield every nested entry of the requested kind under base.
Method __absolute Return the absolute path for an already normalized path.
Method __buildUrl Build the public URL for normalized.
Method __commitStream Promote a finished temp file to its final destination.
Method __copySync Copy source to target synchronously.
Method __downloadSync Copy normalized to a local destination synchronously.
Method __fileMode Return the POSIX file mode for visibility.
Method __hashSync Compute the content hash of normalized synchronously.
Method __infoSync Build a metadata snapshot for normalized synchronously.
Method __init__ Initialize the driver rooted at root.
Method __listSync List entries under normalized synchronously.
Method __moveSync Move source to target synchronously.
Method __openRead Open the file at normalized synchronously.
Method __openTemp Open a temporary sibling file for writing synchronously.
Method __readSync Read the file at normalized synchronously.
Method __relative Return the canonical relative path for absolute.
Method __statOrFail Stat the file at normalized or raise when it is absent.
Method __visibilityFromMode Derive the visibility level from POSIX permission bits.
Method __writeSync Atomically write data to normalized synchronously.
Method absolutePath Return the absolute filesystem path of the file at path.
Async Method copy Copy the file at source to target.
Async Method createDirectory Create the directory at path, including missing parents.
Async Method delete Delete the file at path.
Async Method deleteDirectory Recursively delete the directory at path.
Async Method directories List the directory paths contained in the directory at path.
Async Method directoryExists Check whether a directory exists at path.
Async Method download Copy the file at path to a location on the local filesystem.
Async Method exists Check whether a file exists at path.
Async Method files List the file paths contained in the directory at path.
Async Method hash Compute the content hash of the file at path.
Async Method info Collect a metadata snapshot for the file at path.
Async Method lastModified Return the last-modification timestamp of the file at path.
Async Method mimeType Guess the MIME type of the file at path.
Async Method move Move the file at source to target.
Method open Open an asynchronous binary stream for the file at path.
Async Method read Read the full contents of the file at path.
Async Method readStream Stream the contents of the file at path in chunks.
Method relativePath Return the filesystem path relative to the application base path.
Async Method setVisibility Change the visibility of the file at path.
Async Method size Return the size in bytes of the file at path.
Async Method temporaryUrl Build a signed, time-limited URL for the file at path.
Async Method url Build the public URL for the file at path.
Async Method visibility Return the visibility of the file at path.
Async Method write Write contents to path, replacing any existing file.
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_path Application base path used for project-relative file paths.
Instance Variable _base_url Base URL used to build public file URLs, or None when the disk does not expose URLs.
Instance Variable _root Directory acting as the disk root. It is created when missing.
def __iterEntries(base: Path, *, want_dirs: bool) -> Iterator[Path]: (source)

Yield the direct children of the requested kind under base.

Parameters
base:pathlib.PathAbsolute directory to inspect.
want_dirs:boolWhen True, yield directories; otherwise files.
Yields
pathlib.PathAbsolute path of each matching entry.
def __tempPath(absolute: Path) -> Path: (source)

Build a unique staging path for an atomic write.

Parameters
absolute:pathlib.PathFinal absolute destination path.
Returns
pathlib.PathSibling path carrying a random infix, so concurrent writers never share a staging file, and still ending in .tmp so listings keep filtering it out.
def __walkEntries(base: Path, *, want_dirs: bool) -> Iterator[Path]: (source)

Yield every nested entry of the requested kind under base.

Parameters
base:pathlib.PathAbsolute directory used as the traversal root.
want_dirs:boolWhen True, yield directories; otherwise files.
Yields
pathlib.PathAbsolute path of each matching entry.
def __absolute(self: Self, normalized: str) -> Path: (source)

Return the absolute path for an already normalized path.

Parameters
normalized:strCanonical root-relative path.
Returns
pathlib.PathAbsolute path inside the disk root.
def __buildUrl(self: Self, normalized: str) -> str: (source)

Build the public URL for normalized.

Parameters
normalized:strCanonical root-relative file path.
Returns
strURL composed from the configured base URL.
def __commitStream(self: Self, tmp: Path, absolute: Path, visibility: str | None): (source)

Promote a finished temp file to its final destination.

Parameters
tmp:pathlib.PathFully written temporary file.
absolute:pathlib.PathFinal absolute destination path.
visibility:str | NoneVisibility to apply, or None to keep the OS default.
Returns
NoneNo return value.
def __copySync(self: Self, source: str, target: str): (source)

Copy source to target synchronously.

Parameters
source:strCanonical root-relative source path.
target:strCanonical root-relative destination path.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the source file does not exist.
def __downloadSync(self: Self, normalized: str, destination: str | Path) -> Path: (source)

Copy normalized to a local destination synchronously.

Parameters
normalized:strCanonical root-relative file path.
destination:str | pathlib.PathLocal target file or existing directory.
Returns
pathlib.PathAbsolute local path of the downloaded file.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file does not exist.
def __fileMode(self: Self, visibility: str) -> int: (source)

Return the POSIX file mode for visibility.

Parameters
visibility:strVisibility level ('public' or 'private').
Returns
intPermission bits to apply to the file.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf visibility is not a supported level.
def __hashSync(self: Self, normalized: str, algorithm: str) -> str: (source)

Compute the content hash of normalized synchronously.

Parameters
normalized:strCanonical root-relative file path.
algorithm:strAny algorithm name accepted by hashlib.new.
Returns
strHexadecimal digest of the file contents.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file does not exist.
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf algorithm is not available.
def __infoSync(self: Self, normalized: str) -> FileInfo: (source)

Build a metadata snapshot for normalized synchronously.

Parameters
normalized:strCanonical root-relative file path.
Returns
orionis.storage.entities.FileInfoImmutable metadata snapshot of the file.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file does not exist.
def __init__(self: Self, root: Path, base_url: str | None = None, *, base_path: Path | None = None): (source)

Initialize the driver rooted at root.

Parameters
root:pathlib.PathDirectory acting as the disk root. It is created when missing.
base_url:str | NoneBase URL used to build public file URLs, or None when the disk does not expose URLs.
base_path:pathlib.Path | NoneApplication base path used by relativePath(), or None when the driver is constructed without application context.
Returns
NoneNo return value.
def __listSync(self: Self, normalized: str, *, recursive: bool, want_dirs: bool) -> list[str]: (source)

List entries under normalized synchronously.

Parameters
normalized:strCanonical root-relative directory path.
recursive:boolWhen True, traverse the whole subtree.
want_dirs:boolWhen True, collect directories; otherwise files.
Returns
list[str]Sorted root-relative entry paths.
def __moveSync(self: Self, source: str, target: str): (source)

Move source to target synchronously.

Parameters
source:strCanonical root-relative source path.
target:strCanonical root-relative destination path.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the source file does not exist.
def __openRead(self: Self, normalized: str, mode: str) -> BinaryIO: (source)

Open the file at normalized synchronously.

Parameters
normalized:strCanonical root-relative file path.
mode:strBinary mode to open the file with.
Returns
typing.BinaryIOOpen binary handle.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file does not exist.
OSErrorIf opening is denied or the filesystem reports another I/O failure.
def __openTemp(self: Self, tmp: Path, visibility: str | None = None) -> BinaryIO: (source)

Open a temporary sibling file for writing synchronously.

Parameters
tmp:pathlib.PathAbsolute path of the temporary file.
visibility:str | NoneRequested permissions applied when the staging file is created.
Returns
typing.BinaryIOOpen binary handle in write mode.
def __readSync(self: Self, normalized: str) -> bytes: (source)

Read the file at normalized synchronously.

Parameters
normalized:strCanonical root-relative file path.
Returns
bytesComplete file contents.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file does not exist.
OSErrorIf reading is denied or the filesystem reports another I/O failure.
def __relative(self: Self, absolute: Path) -> str: (source)

Return the canonical relative path for absolute.

Parameters
absolute:pathlib.PathAbsolute path inside the disk root.
Returns
strRoot-relative path using / as separator.
def __statOrFail(self: Self, normalized: str) -> tuple[Path, os.stat_result]: (source)

Stat the file at normalized or raise when it is absent.

Parameters
normalized:strCanonical root-relative file path.
Returns
tuple[pathlib.Path, os.stat_result]The absolute path and its os.stat_result.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the path does not reference an existing file.
OSErrorIf metadata cannot be read for a reason other than absence.
def __visibilityFromMode(self: Self, mode: int) -> str: (source)

Derive the visibility level from POSIX permission bits.

Parameters
mode:intRaw st_mode value of the file.
Returns
str'public' when group or others can read the file, otherwise 'private'.
def __writeSync(self: Self, normalized: str, data: bytes, visibility: str | None): (source)

Atomically write data to normalized synchronously.

Parameters
normalized:strCanonical root-relative file path.
data:bytesRaw bytes to persist.
visibility:str | NoneVisibility to apply, or None to keep the OS default.
Returns
NoneNo return value.
def absolutePath(self: Self, path: str) -> str: (source)

Return the absolute filesystem path of the file at path.

The file does not need to exist. Apply the same disk boundary validation used by content operations, including symbolic links.

Parameters
path:strRoot-relative file path.
Returns
strAbsolute path using the operating system's separators.
Raises
orionis.storage.exceptions.StoragePathExceptionIf path is invalid or escapes the disk root.
async def copy(self: Self, source: str, target: str): (source)

Copy the file at source to target.

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

Create the directory at path, including missing parents.

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

Delete the file at path.

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

Recursively delete the directory at path.

Parameters
path:strRoot-relative directory path.
Returns
boolTrue if the directory existed and was removed.
async def directories(self: Self, path: str = '', *, recursive: bool = False) -> list[str]: (source)

List the directory paths contained in the directory at path.

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

Check whether a directory exists at path.

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

Copy the file at path to a location on 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 file does not exist.
async def exists(self: Self, path: str) -> bool: (source)

Check whether a file exists at path.

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

List the file paths contained in the directory at path.

Parameters
path:strRoot-relative directory path. Empty string for the root.
recursive:boolWhen True, include files from all nested directories.
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 file at path.

Parameters
path:strRoot-relative file path.
algorithm:strAny algorithm name accepted by hashlib.new.
Returns
strHexadecimal digest of the file contents.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file does not exist.
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf algorithm is not available.
async def info(self: Self, path: str) -> FileInfo: (source)

Collect a metadata snapshot for the file at path.

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

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

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

Guess the MIME type of the file at path.

The guess is derived from the file extension and requires no disk access.

Parameters
path:strRoot-relative file path.
Returns
str | NoneMIME type, or None when it cannot be determined.
async def move(self: Self, source: str, target: str): (source)

Move the file at source to target.

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

Open an asynchronous binary stream for the file at path.

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 file at path.

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

Stream the contents of the file at path in chunks.

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

Return the filesystem path relative to the application base path.

The file does not need to exist. Roots outside the project may require leading .. segments in the returned path.

Parameters
path:strRoot-relative file path.
Returns
strPath from the application base path using / as separator.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf no application base path was supplied to the driver.
orionis.storage.exceptions.StoragePathExceptionIf path is invalid, escapes the disk root, or is on a different filesystem drive from the application base path.
async def setVisibility(self: Self, path: str, visibility: str): (source)

Change the visibility of the file at path.

Parameters
path:strRoot-relative file path.
visibility:strTarget visibility ('public' or 'private').
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file 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 file at path.

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

Build a signed, time-limited URL for the file at path.

The local driver cannot sign URLs, so this operation always fails.

Parameters
path:strRoot-relative file path.
expires_in:intLifetime of the URL in seconds.
Returns
strNever returned by this driver.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionAlways, since local disks cannot sign URLs.
async def url(self: Self, path: str) -> str: (source)

Build the public URL for the file at path.

Parameters
path:strRoot-relative file path.
Returns
strPublicly accessible URL for the file.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf the disk has no base URL configured.
async def visibility(self: Self, path: str) -> str: (source)

Return the visibility of the file at path.

Parameters
path:strRoot-relative file path.
Returns
str'public' or 'private'.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file 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 file.

The write is atomic: data lands in a sibling temporary file that is renamed over the destination once complete.

Parameters
path:strRoot-relative file path.
contents:bytes | strData to persist. Strings are encoded as UTF-8.
visibility:str | NoneVisibility to apply, or None to keep the OS 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.

Chunks are appended to a temporary file that atomically replaces the destination once the stream is exhausted, so a failed transfer never leaves a partial file behind.

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

Declare the instance attribute slots reserved by this class.

_base_path: Path | None = (source)

Application base path used for project-relative file paths.

_base_url: str | None = (source)

Base URL used to build public file URLs, or None when the disk does not expose URLs.

_root: Path = (source)

Directory acting as the disk root. It is created when missing.