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

class GoogleStorageDriver(IStorageDriver): (source)

Constructor: GoogleStorageDriver(config)

View In Hierarchy

Storage driver backed by Google Cloud Storage.

Uses the official Google Cloud client library (google-cloud-storage), which is an optional dependency: it is not installed with the framework. Install it before using this driver:

uv add 'orionis[gcs]'

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 object names and explicit directories are stored as zero-byte path/ markers. Authentication uses the configured service-account key file or Application Default Credentials.

Method __aclFor Map a visibility level onto a GCS predefined ACL.
Method __blob Return a lightweight blob handle for normalized.
Method __blobOrFail Fetch a blob with loaded metadata or raise when absent.
Method __bucket Return the bucket handle, bootstrapping the client on first use.
Method __init__ Initialize the driver from a GCS disk configuration entity.
Method __isPublicSync Check whether a blob grants read access to anonymous users.
Method __listKeysSync List every object name under prefix.
Method __missing Build the framework exception for a missing object.
Method __seedStream Seed a stream buffer and position it for the requested mode.
Method __urlFor Compose the public URL of an object without SDK involvement.
Async Method copy Copy the object at source to target server-side.
Async Method createDirectory Create a zero-byte directory marker at path.
Async Method delete Delete the object at path.
Async Method deleteDirectory Recursively delete every object under path.
Async Method directories List the directory prefixes contained under path.
Async Method directoryExists Check whether any object exists under path.
Async Method download Download the object at path to the local filesystem.
Async Method exists Check whether an object exists at path.
Async Method files List the object names that represent files under path.
Async Method hash Compute the content hash of the object at path.
Async Method info Collect a metadata snapshot for the object at path.
Async Method lastModified Return the last-modification timestamp of the object at path.
Async Method mimeType Return the MIME type of the object at path.
Async Method move Move the object at source to target.
Method open Open an asynchronous binary stream for the object at path.
Async Method read Read the full contents of the object at path.
Async Method readStream Stream the contents of the object at path in chunks.
Async Method setVisibility Change the visibility of the object at path.
Async Method size Return the size in bytes of the object at path.
Async Method temporaryUrl Build a V4 signed URL for the object at path.
Async Method url Build the public URL for the object at path.
Async Method visibility Return the visibility of the object at path.
Async Method write Write contents to path, replacing any existing object.
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_url Base URL used when constructing public resource URLs.
Instance Variable _bucket Cloud-storage bucket containing the driver resources.
Instance Variable _bucket_name Bucket name produced by str.
Instance Variable _client_lock Serialize lazy SDK initialization across worker threads.
Instance Variable _cloud_error Cloud error supplied through Exception.
Instance Variable _key_file Credential file used to initialize the cloud-storage client.
Instance Variable _not_found Not found supplied through Exception.
Instance Variable _project Project produced by str.

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 __aclFor(self: Self, visibility: str) -> str: (source)

Map a visibility level onto a GCS predefined ACL.

Parameters
visibility:strVisibility level ('public' or 'private').
Returns
strPredefined ACL name.
Raises
orionis.storage.exceptions.UnsupportedStorageOperationExceptionIf visibility is not a supported level.
def __blob(self: Self, normalized: str) -> Any: (source)

Return a lightweight blob handle for normalized.

Parameters
normalized:strCanonical root-relative file path.
Returns
typing.AnyBlob handle bound to the bucket.
def __blobOrFail(self: Self, normalized: str) -> Any: (source)

Fetch a blob with loaded metadata or raise when absent.

Parameters
normalized:strCanonical root-relative file path.
Returns
typing.AnyBlob with populated properties.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object does not exist.
def __bucket(self: Self) -> Any: (source)

Return the bucket handle, bootstrapping the client on first use.

Returns
typing.AnyConfigured Bucket instance.
Raises
orionis.storage.exceptions.MissingStorageDependencyExceptionIf google-cloud-storage is not installed.
def __init__(self: Self, config: object): (source)

Initialize the driver from a GCS disk configuration entity.

No SDK import or network activity happens here; the client is bootstrapped lazily on first use.

Parameters
config:objectDisk configuration exposing project_id, key_file, bucket, and url.
Returns
NoneNo return value.
def __isPublicSync(self: Self, blob: Any) -> bool: (source)

Check whether a blob grants read access to anonymous users.

Parameters
blob:typing.AnyBlob with loaded metadata.
Returns
boolTrue when allUsers holds a reader or owner role. False when ACLs cannot be inspected (e.g. uniform bucket-level access).
def __listKeysSync(self: Self, prefix: str) -> list[str]: (source)

List every object name under prefix.

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

Build the framework exception for a missing object.

Parameters
normalized:strCanonical root-relative file path.
Returns
orionis.storage.exceptions.StorageFileNotFoundExceptionException instance ready to be raised.
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 an object without SDK involvement.

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

Copy the object at source to target server-side.

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

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

Recursively delete every object under path.

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

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

Check whether an object exists at path.

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

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

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

The snapshot is built from object metadata only; checksum holds the MD5 hash stored by GCS 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 object does not exist.
async def lastModified(self: Self, path: str) -> datetime: (source)

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

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

Return the MIME type of the object at path.

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

Move the object at source to target.

Implemented as a server-side copy followed by a delete of the source object.

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

Open an asynchronous binary stream for the object at path.

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

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

Stream the contents of the object at path in chunks.

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

Change the visibility of the object at path.

Not available on buckets with uniform bucket-level access, where the SDK raises the corresponding API error.

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

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

Build a V4 signed URL for the object at path.

Requires credentials with a private key (a service-account key file); plain Application Default Credentials without a key cannot sign URLs.

Parameters
path:strRoot-relative file path.
expires_in:intLifetime of the URL in seconds.
Returns
strSigned GET URL valid for expires_in seconds.
Raises
orionis.storage.exceptions.MissingStorageDependencyExceptionIf google-cloud-storage is not installed.
async def url(self: Self, path: str) -> str: (source)

Build the public URL for the object at path.

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

Return the visibility of the object at path.

Parameters
path:strRoot-relative file path.
Returns
str'public' when anonymous users can read the object, otherwise 'private'.
Raises
orionis.storage.exceptions.StorageFileNotFoundExceptionIf the object 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 object.

Parameters
path:strRoot-relative file path.
contents:bytes | strData to persist. Strings are encoded as UTF-8.
visibility:str | NoneVisibility applied through a predefined ACL, or None for the bucket default. Ignored by GCS when the bucket enforces uniform bucket-level access.
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 with the SDK's resumable transfer.

Parameters
path:strRoot-relative file path.
stream:collections.abc.AsyncIterable[bytes]Asynchronous byte-chunk producer.
visibility:str | NoneVisibility applied through a predefined ACL, or None for the bucket default.
Returns
NoneNo return value.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_base_url: str | None = (source)

Base URL used when constructing public resource URLs.

_bucket: Any = (source)

Cloud-storage bucket containing the driver resources.

_bucket_name: str = (source)

Bucket name produced by str.

_client_lock = (source)

Serialize lazy SDK initialization across worker threads.

_cloud_error: type[Exception] = (source)

Cloud error supplied through Exception.

_key_file: str | None = (source)

Credential file used to initialize the cloud-storage client.

Not found supplied through Exception.

_project: str = (source)

Project produced by str.