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 Azure Blob Storage.

Uses the official Azure SDK for Python (azure-storage-blob), which is an optional dependency: it is not installed with the framework. Install it before using this driver:

uv add 'orionis[azure]'

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. Directories are virtual: prefixes are inferred from blob names and explicit directories are stored as zero-byte path/ markers. Azure has no per-blob visibility: orionis.storage.drivers.AzureStorageDriver.visibility reflects the container access level and orionis.storage.drivers.AzureStorageDriver.setVisibility is unsupported.

Method __blob Return the blob client for normalized.
Method __containerClient Return the container client, bootstrapping it on first use.
Method __contentSettings Build the content settings for an upload, when derivable.
Method __init__ Initialize the driver from an Azure disk configuration entity.
Method __listKeysSync List every blob name under prefix.
Method __missing Build the framework exception for a missing blob.
Method __propsSync Fetch blob properties or raise when the blob is absent.
Method __seedStream Seed a stream buffer and position it for the requested mode.
Method __urlFor Compose the public URL of a blob without SDK involvement.
Async Method copy Copy the blob at source to target.
Async Method createDirectory Create a zero-byte directory marker at path.
Async Method delete Delete the blob at path.
Async Method deleteDirectory Recursively delete every blob under path.
Async Method directories List the directory prefixes contained under path.
Async Method directoryExists Check whether any blob exists under path.
Async Method download Download the blob at path to the local filesystem.
Async Method exists Check whether a blob exists at path.
Async Method files List the blob names that represent files under path.
Async Method hash Compute the content hash of the blob at path.
Async Method info Collect a metadata snapshot for the blob at path.
Async Method lastModified Return the last-modification timestamp of the blob at path.
Async Method mimeType Return the MIME type of the blob at path.
Async Method move Move the blob at source to target.
Method open Open an asynchronous binary stream for the blob at path.
Async Method read Read the full contents of the blob at path.
Async Method readStream Stream the contents of the blob at path in chunks.
Async Method setVisibility Change the visibility of the blob at path.
Async Method size Return the size in bytes of the blob at path.
Async Method temporaryUrl Build a SAS URL for the blob at path.
Async Method url Build the public URL for the blob at path.
Async Method visibility Return the effective visibility of the blob at path.
Async Method write Write contents to path, replacing any existing blob.
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 _account_key Account key produced by str.
Instance Variable _account_name Account name produced by str.
Instance Variable _base_url Base URL used when constructing public resource URLs.
Instance Variable _client_lock Serialize lazy SDK initialization across worker threads.
Instance Variable _connection_string Connection string produced by str.
Instance Variable _container Azure Blob container used by the storage driver.
Instance Variable _container_name Container name produced by str.
Instance Variable _http_error Http error supplied through Exception.
Instance Variable _not_found Not found supplied through Exception.
Instance Variable _sdk Loaded cloud-storage SDK used by the configured driver.

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 __blob(self: Self, normalized: str) -> Any: (source)

Return the blob client for normalized.

Parameters
normalized:strCanonical root-relative file path.
Returns
typing.AnyBlobClient bound to the blob.
def __containerClient(self: Self) -> Any: (source)

Return the container client, bootstrapping it on first use.

Returns
typing.AnyConfigured ContainerClient instance.
Raises
orionis.storage.exceptions.MissingStorageDependencyExceptionIf azure-storage-blob is not installed.
def __contentSettings(self: Self, normalized: str) -> Any: (source)

Build the content settings for an upload, when derivable.

Parameters
normalized:strCanonical root-relative file path.
Returns
typing.AnyContentSettings with the guessed MIME type, or None when no type could be guessed.
def __init__(self: Self, config: object): (source)

Initialize the driver from an Azure disk configuration entity.

No SDK import or network activity happens here; the client is bootstrapped lazily on first use. When a connection string is provided, the account name and key are parsed from it so URLs and SAS tokens can be produced.

Parameters
config:objectDisk configuration exposing connection_string, account_name, account_key, container, and url.
Returns
NoneNo return value.
def __listKeysSync(self: Self, prefix: str) -> list[str]: (source)

List every blob name under prefix.

Parameters
prefix:strName prefix to filter by; empty string lists everything.
Returns
list[str]All matching blob names, including directory markers.
def __missing(self: Self, normalized: str) -> StorageFileNotFoundException: (source)

Build the framework exception for a missing blob.

Parameters
normalized:strCanonical root-relative file path.
Returns
orionis.storage.exceptions.StorageFileNotFoundExceptionException instance ready to be raised.
def __propsSync(self: Self, normalized: str) -> Any: (source)

Fetch blob properties or raise when the blob is absent.

Parameters
normalized:strCanonical root-relative file path.
Returns
typing.AnyBlobProperties for the blob.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the blob does not exist.
def __seedStream(self: Self, buffer: BinaryIO, normalized: str, mode: str): (source)

Seed a stream buffer and position it for the requested mode.

Missing objects are tolerated for append modes and rejected for read modes. The caller retains ownership of the buffer during failures.

Parameters
buffer:typing.BinaryIOOwned temporary buffer receiving existing content.
normalized:strCanonical root-relative object path.
mode:strValidated binary read or append mode.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist and the mode requires it.
def __urlFor(self: Self, normalized: str) -> str: (source)

Compose the public URL of a blob without SDK involvement.

Parameters
normalized:strCanonical root-relative file path.
Returns
strURL derived from the configured base URL or the canonical Azure Blob endpoint.
async def copy(self: Self, source: str, target: str): (source)

Copy the blob at source to target.

The content is streamed through a spooled local buffer, which works with any authentication mode and never loads large blobs fully into memory.

Parameters
source:strRoot-relative path of the existing blob.
target:strRoot-relative destination path.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the source blob 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 blob at path.

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

Recursively delete every blob under path.

Parameters
path:strRoot-relative directory path. The empty string clears the whole container prefix space.
Returns
boolTrue if at least one blob was removed.
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 blob 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 blob.
async def download(self: Self, path: str, destination: str | Path) -> Path: (source)

Download the blob 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 blob does not exist.
async def exists(self: Self, path: str) -> bool: (source)

Check whether a blob exists at path.

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

List the blob names 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 blob at path.

The blob 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 blob contents.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the blob 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 blob at path.

The snapshot is built from blob properties only; checksum holds the Content-MD5 stored by Azure when available.

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 blob does not exist.
async def lastModified(self: Self, path: str) -> datetime: (source)

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

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

Return the MIME type of the blob at path.

Prefers the content type stored in Azure 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 blob does not exist.
async def move(self: Self, source: str, target: str): (source)

Move the blob at source to target.

Implemented as a copy followed by a delete of the source blob.

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

Open an asynchronous binary stream for the blob at path.

Read-oriented modes download the blob into a spooled temporary buffer; writable modes upload the buffered content back to Azure 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 blob at path.

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

Stream the contents of the blob at path in chunks.

Chunk sizing follows the SDK transfer configuration; the chunk_size parameter is advisory for this driver.

Parameters
path:strRoot-relative file path.
chunk_size:intAdvisory chunk size in bytes.
Yields
bytesConsecutive chunks of the blob contents.
Raises
ValueErrorIf the advisory chunk size is not a positive integer.
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the blob does not exist.
async def setVisibility(self: Self, path: str, visibility: str): (source)

Change the visibility of the blob at path.

Azure Blob Storage does not support per-blob visibility, so this operation always fails. Adjust the container access level from the Azure portal or management SDK instead.

Parameters
path:strRoot-relative file path.
visibility:strRequested visibility level.
Returns
NoneNo return value.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionAlways, since Azure has no per-blob visibility.
async def size(self: Self, path: str) -> int: (source)

Return the size in bytes of the blob at path.

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

Build a SAS URL for the blob at path.

Requires the storage account key, either configured explicitly or embedded in the connection string.

Parameters
path:strRoot-relative file path.
expires_in:intLifetime of the URL in seconds.
Returns
strRead-only SAS URL valid for expires_in seconds.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf no account key is available for signing.
orionis.storage.exceptions.MissingStorageDependencyExceptionIf azure-storage-blob is not installed.
async def url(self: Self, path: str) -> str: (source)

Build the public URL for the blob at path.

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

Return the effective visibility of the blob at path.

Azure controls access at container level, so the result reflects the container access policy rather than a per-blob ACL.

Parameters
path:strRoot-relative file path.
Returns
str'public' when the container allows anonymous access, otherwise 'private'.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the blob 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 blob.

Azure Blob Storage has no per-blob visibility; access is governed by the container access level, so visibility is accepted for interface compatibility but ignored.

Parameters
path:strRoot-relative file path.
contents:bytes | strData to persist. Strings are encoded as UTF-8.
visibility:str | NoneIgnored by this driver.
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 in blocks by the SDK.

Parameters
path:strRoot-relative file path.
stream:collections.abc.AsyncIterable[bytes]Asynchronous byte-chunk producer.
visibility:str | NoneIgnored by this driver.
Returns
NoneNo return value.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_account_key: str = (source)

Account key produced by str.

_account_name: str = (source)

Account name produced by str.

_base_url: str | None = (source)

Base URL used when constructing public resource URLs.

_client_lock = (source)

Serialize lazy SDK initialization across worker threads.

_connection_string: str = (source)

Connection string produced by str.

_container: Any = (source)

Azure Blob container used by the storage driver.

_container_name: str = (source)

Container name produced by str.

Http error supplied through Exception.

Not found supplied through Exception.

_sdk: Any = (source)

Loaded cloud-storage SDK used by the configured driver.