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 S3StorageDriver(IStorageDriver): (source)
Constructor: S3StorageDriver(config)
Storage driver backed by Amazon S3 (or S3-compatible services).
Uses the official AWS SDK for Python (boto3), which is an optional dependency: it is not installed with the framework. Install it before using this driver:
uv add 'orionis[s3]'
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 so the
event loop stays responsive. Directories are virtual: prefixes are
inferred from object keys, and explicit directories are stored as
zero-byte path/ marker objects.
| Method | __acl |
Map a visibility level onto an S3 canned ACL. |
| Method | __client |
Return the boto3 S3 client, bootstrapping it on first use. |
| Method | __head |
Fetch object metadata or raise when the object is absent. |
| Method | __init__ |
Initialize the driver from an S3 disk configuration entity. |
| Method | __is |
Check whether an SDK error denotes a missing object. |
| Method | __list |
List every object key under prefix. |
| Method | __missing |
Build the framework exception for a missing object. |
| Method | __put |
Build the optional arguments for an object upload. |
| Method | __seed |
Seed buffer with the current object content for a stream. |
| Method | __url |
Compose the public URL of an object without SDK involvement. |
| Method | __visibility |
Resolve the object visibility from its ACL grants. |
| Async Method | copy |
Copy the object at source to target server-side. |
| Async Method | create |
Create a zero-byte directory marker at path. |
| Async Method | delete |
Delete the object at path. |
| Async Method | delete |
Recursively delete every object under path. |
| Async Method | directories |
List the directory prefixes contained under path. |
| Async Method | directory |
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 keys 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 | last |
Return the last-modification timestamp of the object at path. |
| Async Method | mime |
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 | read |
Stream the contents of the object at path in chunks. |
| Async Method | set |
Change the visibility of the object at path. |
| Async Method | size |
Return the size in bytes of the object at path. |
| Async Method | temporary |
Build a presigned 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 | write |
Write the chunks produced by stream to path. |
| Class Variable | __slots__ |
Declare the instance attribute slots reserved by this class. |
| Instance Variable | _base |
Base URL used when constructing public resource URLs. |
| Instance Variable | _bucket |
Cloud-storage bucket containing the driver resources. |
| Instance Variable | _client |
Client used to communicate with the configured backend. |
| Instance Variable | _client |
Client error supplied through Exception. |
| Instance Variable | _client |
Serialize lazy SDK initialization across worker threads. |
| Instance Variable | _endpoint |
Configured endpoint used to contact the storage service. |
| Instance Variable | _key |
Key produced by str. |
| Instance Variable | _region |
Region produced by str. |
| Instance Variable | _secret |
Secret produced by str. |
| Instance Variable | _use |
Use path style produced by bool. |
Inherited from IStorageDriver:
| Method | absolute |
Return the absolute filesystem path of the file at path. |
| Method | relative |
Return the filesystem path relative to the application base path. |
Map a visibility level onto an S3 canned ACL.
| Parameters | |
visibility:str | Visibility level ('public' or 'private'). |
| Returns | |
str | Canned ACL name. |
| Raises | |
orionis.storage.exceptions.UnsupportedStorageOperationException | If visibility is not a supported level. |
Return the boto3 S3 client, bootstrapping it on first use.
| Returns | |
typing.Any | Configured boto3 S3 client. |
| Raises | |
orionis.storage.exceptions.MissingStorageDependencyException | If boto3 is not installed. |
Fetch object metadata or raise when the object is absent.
| Parameters | |
normalized:str | Canonical root-relative file path. |
| Returns | |
dict | Raw head_object response. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Initialize the driver from an S3 disk configuration entity.
No SDK import or network activity happens here; the client is bootstrapped lazily on first use.
| Parameters | |
config:object | Disk configuration exposing bucket, region, key, secret, url, endpoint, and use_path_style_endpoint. |
| Returns | |
None | No return value. |
Build the framework exception for a missing object.
| Parameters | |
normalized:str | Canonical root-relative file path. |
| Returns | |
orionis.storage.exceptions.StorageFileNotFoundException | Exception instance ready to be raised. |
Seed buffer with the current object content for a stream.
Downloads the object into the buffer and positions the cursor according to mode. Missing objects are tolerated for append modes and rejected for read modes.
| Parameters | |
buffer:typing.BinaryIO | Spooled buffer backing the stream. |
normalized:str | Canonical root-relative file path. |
mode:str | Binary mode requested by the caller. |
| Returns | |
None | No return value. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist and mode requires it. |
Resolve the object visibility from its ACL grants.
| Parameters | |
normalized:str | Canonical root-relative file path. |
| Returns | |
str | 'public' when anonymous users hold a read grant, otherwise 'private'. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Copy the object at source to target server-side.
| Parameters | |
source:str | Root-relative path of the existing object. |
target:str | Root-relative destination path. |
| Returns | |
None | No return value. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the source object does not exist. |
Recursively delete every object under path.
| Parameters | |
path:str | Root-relative directory path. The empty string clears the whole bucket prefix space. |
| Returns | |
bool | True if at least one object was removed. |
| Raises | |
botocore.exceptions.ClientError | If a batch reports a per-object failure. The exception retains the complete response, including successful deletions and errors. |
Self, path: str = '', *, recursive: bool = False) -> list[ str]:
(source)
¶
Download the object at path to the local filesystem.
| Parameters | |
path:str | Root-relative file path on the disk. |
destination:str | pathlib.Path | Local target. When it points to an existing directory the file keeps its original name inside that directory. |
| Returns | |
pathlib.Path | Absolute local path of the downloaded file. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
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:str | Root-relative file path. |
algorithm:str | Fixed-length digest algorithm accepted by hashlib.new. |
| Returns | |
str | Hexadecimal digest of the object contents. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
orionis.storage.exceptions.UnsupportedStorageOperationException | If algorithm is unavailable or requires an explicit digest length. |
Collect a metadata snapshot for the object at path.
The snapshot is built from object metadata only; the
checksum field is None because computing it would
require a full download (use hash instead).
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
orionis.storage.entities.FileInfo | Immutable entity with size, MIME type, timestamps, ETag, visibility, and URL. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Return the last-modification timestamp of the object at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
datetime.datetime | Timezone-aware modification timestamp. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Return the MIME type of the object at path.
Prefers the Content-Type stored in S3 and falls back to a guess based on the file extension.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
str | None | MIME type, or None when it cannot be determined. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Move the object at source to target.
Implemented as a server-side copy followed by a delete of the source object.
| Parameters | |
source:str | Root-relative path of the existing object. |
target:str | Root-relative destination path. |
| Returns | |
None | No return value. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the source object does not exist. |
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 S3 when the stream is closed.
| Parameters | |
path:str | Root-relative file path. |
mode:str | Binary mode: 'rb', 'wb', 'ab', 'rb+', 'wb+', or 'ab+'. |
| Returns | |
orionis.storage.AsyncStream | Lazily opened stream; use it as an async context manager. |
| Raises | |
orionis.storage.exceptions.UnsupportedStorageOperationException | If mode is not a supported binary mode. |
Read the full contents of the object at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
bytes | Complete object contents. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Self, path: str, chunk_size: int = _CHUNK_SIZE) -> AsyncIterator[ bytes]:
(source)
¶
Stream the contents of the object at path in chunks.
| Parameters | |
path:str | Root-relative file path. |
chunkint | Maximum number of bytes per yielded chunk. |
| Yields | |
bytes | Consecutive chunks of the object contents. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Change the visibility of the object at path.
| Parameters | |
path:str | Root-relative file path. |
visibility:str | Target visibility ('public' or 'private'). |
| Returns | |
None | No return value. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
orionis.storage.exceptions.UnsupportedStorageOperationException | If visibility is not a supported level. |
Return the size in bytes of the object at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
int | Object size in bytes. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Build a presigned URL for the object at path.
| Parameters | |
path:str | Root-relative file path. |
expiresint | Lifetime of the URL in seconds. |
| Returns | |
str | Presigned GET URL valid for expires_in seconds. |
| Raises | |
orionis.storage.exceptions.MissingStorageDependencyException | If boto3 is not installed. |
Return the visibility of the object at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
str | 'public' or 'private' based on the object ACL. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the object does not exist. |
Self, path: str, contents: bytes | str, visibility: str | None = None):
(source)
¶
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 managed transfer, which switches to multipart uploads for large objects.
| Parameters | |
path:str | Root-relative file path. |
stream:collections.abc.AsyncIterable[bytes] | Asynchronous byte-chunk producer. |
visibility:str | None | Visibility to apply, or None for the bucket default. |
| Returns | |
None | No return value. |