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

Define the low-level contract every storage backend must implement.

A driver translates canonical root-relative paths into operations against a physical medium (local disk, memory, S3, Azure, GCS...). Drivers contain no business logic; higher-level behavior lives in orionis.storage.File, orionis.storage.Directory, and orionis.storage.Disk. Prefer those interfaces when application code does not need a backend-specific operation.

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.
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 that this class introduces no additional instance slots.
def absolutePath(self, path: str) -> str: (source)

Return the absolute filesystem path of the file at path.

Drivers with a local filesystem representation may override this operation. The file does not need to exist.

Parameters
path:strRoot-relative file path.
Returns
strAbsolute path using the operating system's separators.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf the driver does not expose local filesystem paths.
orionis.storage.exceptions.StoragePathExceptionIf path is invalid or escapes the disk root.
@abstractmethod
async def copy(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.
@abstractmethod
async def createDirectory(self, path: str): (source)

Create the directory at path, including missing parents.

Parameters
path:strRoot-relative directory path.
Returns
NoneNo return value.
@abstractmethod
async def delete(self, path: str) -> bool: (source)
@abstractmethod
async def deleteDirectory(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.
@abstractmethod
async def directories(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.
@abstractmethod
async def directoryExists(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.
@abstractmethod
async def download(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.
@abstractmethod
async def exists(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.
@abstractmethod
async def files(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.
@abstractmethod
async def hash(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.
@abstractmethod
async def info(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.
@abstractmethod
async def lastModified(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.
@abstractmethod
async def mimeType(self, path: str) -> str | None: (source)

Guess the MIME type of the file at path.

Parameters
path:strRoot-relative file path.
Returns
str | NoneMIME type, or None when it cannot be determined.
@abstractmethod
async def move(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.
@abstractmethod
def open(self, path: str, mode: str = 'rb') -> IStorageStream: (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.contracts.IStorageStreamLazily opened stream; use it as an async context manager.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf mode is not a supported binary mode.
@abstractmethod
async def read(self, path: str) -> bytes: (source)
@abstractmethod
def readStream(self, path: str, chunk_size: int = 65536) -> 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.
Returns
collections.abc.AsyncIterator[bytes]Asynchronous iterator yielding consecutive chunks.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the file does not exist.
def relativePath(self, path: str) -> str: (source)

Return the filesystem path relative to the application base path.

Drivers with a local filesystem representation and an application base path may override this operation. The file need not exist.

Parameters
path:strRoot-relative file path.
Returns
strPath from the application base path using / as separator. Roots outside the project may require leading .. segments.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf local filesystem paths or the application base are unavailable.
orionis.storage.exceptions.StoragePathExceptionIf path is invalid, escapes the disk root, or cannot be expressed relative to the application base path.
@abstractmethod
async def setVisibility(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.
@abstractmethod
async def size(self, path: str) -> int: (source)
@abstractmethod
async def temporaryUrl(self, path: str, expires_in: int) -> str: (source)

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

Parameters
path:strRoot-relative file path.
expires_in:intLifetime of the URL in seconds.
Returns
strTemporary URL valid for expires_in seconds.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf the driver does not support temporary URLs.
@abstractmethod
async def url(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 does not expose public URLs.
@abstractmethod
async def visibility(self, path: str) -> str: (source)
@abstractmethod
async def write(self, path: str, contents: bytes | str, visibility: str | None = None): (source)

Write contents to path, replacing any existing file.

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

Write the chunks produced by stream to path.

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