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.

Explore modules View classes

orionis.storage.contracts.IStorageDriver

class documentation

class IStorageDriver(ABC): (source)

Known subclasses: orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

View In Hierarchy

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.File, ~orionis.storage.directory.Directory, and ~orionis.storage.disk.Disk. User code never interacts with a driver directly.

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.
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__ Undocumented
@abstractmethod
async def copy(self, source: str, target: str): (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Copy the file at source to target.

Parameters
source:strRoot-relative path of the existing file.
target:strRoot-relative destination path.
Returns
NoneUndocumented
Raises
StorageFileNotFoundExceptionIf the source file does not exist.
@abstractmethod
async def createDirectory(self, path: str): (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Create the directory at path, including missing parents.

Parameters
path:strRoot-relative directory path.
Returns
NoneUndocumented
@abstractmethod
async def delete(self, path: str) -> bool: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Delete the file at path.

Parameters
path:strRoot-relative file path.
Returns
boolTrue if the file existed and was removed.
@abstractmethod
async def deleteDirectory(self, path: str) -> bool: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Copy the file at path to a location on the local filesystem.

Parameters
path:strRoot-relative file path on the disk.
destination:str | PathLocal target. When it points to an existing directory the file keeps its original name inside that directory.
Returns
PathAbsolute local path of the downloaded file.
Raises
StorageFileNotFoundExceptionIf the file does not exist.
@abstractmethod
async def exists(self, path: str) -> bool: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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
StorageFileNotFoundExceptionIf the file does not exist.
@abstractmethod
async def info(self, path: str) -> FileInfo: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Collect a metadata snapshot for the file at path.

Parameters
path:strRoot-relative file path.
Returns
FileInfoImmutable entity with size, MIME type, timestamps, hashes, visibility, and URL when available.
Raises
StorageFileNotFoundExceptionIf the file does not exist.
@abstractmethod
async def lastModified(self, path: str) -> datetime: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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

Parameters
path:strRoot-relative file path.
Returns
datetimeTimezone-aware modification timestamp (UTC).
Raises
StorageFileNotFoundExceptionIf the file does not exist.
@abstractmethod
async def mimeType(self, path: str) -> str | None: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Move the file at source to target.

Parameters
source:strRoot-relative path of the existing file.
target:strRoot-relative destination path.
Returns
NoneUndocumented
Raises
StorageFileNotFoundExceptionIf the source file does not exist.
@abstractmethod
def open(self, path: str, mode: str = 'rb') -> IStorageStream: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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
IStorageStreamLazily opened stream; use it as an async context manager.
Raises
UnsupportedStorageOperationExceptionIf mode is not a supported binary mode.
@abstractmethod
async def read(self, path: str) -> bytes: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Read the full contents of the file at path.

Parameters
path:strRoot-relative file path.
Returns
bytesComplete file contents.
Raises
StorageFileNotFoundExceptionIf the file does not exist.
@abstractmethod
def readStream(self, path: str, chunk_size: int = 65536) -> AsyncIterator[bytes]: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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
AsyncIterator[bytes]Asynchronous iterator yielding consecutive chunks.
Raises
StorageFileNotFoundExceptionIf the file does not exist.
@abstractmethod
async def setVisibility(self, path: str, visibility: str): (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Change the visibility of the file at path.

Parameters
path:strRoot-relative file path.
visibility:strTarget visibility ('public' or 'private').
Returns
NoneUndocumented
Raises
StorageFileNotFoundExceptionIf the file does not exist.
UnsupportedStorageOperationExceptionIf visibility is not a supported level.
@abstractmethod
async def size(self, path: str) -> int: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Return the size in bytes of the file at path.

Parameters
path:strRoot-relative file path.
Returns
intFile size in bytes.
Raises
StorageFileNotFoundExceptionIf the file does not exist.
@abstractmethod
async def temporaryUrl(self, path: str, expires_in: int) -> str: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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
UnsupportedStorageOperationExceptionIf the driver does not support temporary URLs.
@abstractmethod
async def url(self, path: str) -> str: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Build the public URL for the file at path.

Parameters
path:strRoot-relative file path.
Returns
strPublicly accessible URL for the file.
Raises
UnsupportedStorageOperationExceptionIf the disk does not expose public URLs.
@abstractmethod
async def visibility(self, path: str) -> str: (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Return the visibility of the file at path.

Parameters
path:strRoot-relative file path.
Returns
str'public' or 'private'.
Raises
StorageFileNotFoundExceptionIf the file does not exist.
@abstractmethod
async def write(self, path: str, contents: bytes | str, visibility: str | None = None): (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

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
NoneUndocumented
@abstractmethod
async def writeStream(self, path: str, stream: AsyncIterable[bytes], visibility: str | None = None): (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Write the chunks produced by stream to path.

Parameters
path:strRoot-relative file path.
stream:AsyncIterable[bytes]Asynchronous byte-chunk producer.
visibility:str | NoneVisibility to apply, or None for the medium default.
Returns
NoneUndocumented
__slots__: tuple = (source)
overridden in orionis.storage.drivers.AzureStorageDriver, orionis.storage.drivers.GoogleStorageDriver, orionis.storage.drivers.LocalStorageDriver, orionis.storage.drivers.MemoryStorageDriver, orionis.storage.drivers.S3StorageDriver

Undocumented