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 LocalStorageDriver(IStorageDriver): (source)
Constructor: LocalStorageDriver(root, base_url, base_path)
Storage driver backed by the local filesystem.
Every path is resolved inside the configured root directory. Content
and metadata I/O runs on worker threads via asyncio.to_thread,
keeping the event loop responsive. Path accessors are synchronous and
validate filesystem boundaries without requiring the file to exist.
Visibility is mapped onto POSIX permission bits (0o644/0o600
for files), which degrades gracefully on platforms without a full
POSIX mode implementation.
Preserve permission and device failures as their original I/O exceptions. Missing paths retain the normal missing-file or empty existence results.
| Static Method | __iter |
Yield the direct children of the requested kind under base. |
| Static Method | __temp |
Build a unique staging path for an atomic write. |
| Static Method | __walk |
Yield every nested entry of the requested kind under base. |
| Method | __absolute |
Return the absolute path for an already normalized path. |
| Method | __build |
Build the public URL for normalized. |
| Method | __commit |
Promote a finished temp file to its final destination. |
| Method | __copy |
Copy source to target synchronously. |
| Method | __download |
Copy normalized to a local destination synchronously. |
| Method | __file |
Return the POSIX file mode for visibility. |
| Method | __hash |
Compute the content hash of normalized synchronously. |
| Method | __info |
Build a metadata snapshot for normalized synchronously. |
| Method | __init__ |
Initialize the driver rooted at root. |
| Method | __list |
List entries under normalized synchronously. |
| Method | __move |
Move source to target synchronously. |
| Method | __open |
Open the file at normalized synchronously. |
| Method | __open |
Open a temporary sibling file for writing synchronously. |
| Method | __read |
Read the file at normalized synchronously. |
| Method | __relative |
Return the canonical relative path for absolute. |
| Method | __stat |
Stat the file at normalized or raise when it is absent. |
| Method | __visibility |
Derive the visibility level from POSIX permission bits. |
| Method | __write |
Atomically write data to normalized synchronously. |
| Method | absolute |
Return the absolute filesystem path of the file at path. |
| Async Method | copy |
Copy the file at source to target. |
| Async Method | create |
Create the directory at path, including missing parents. |
| Async Method | delete |
Delete the file at path. |
| Async Method | delete |
Recursively delete the directory at path. |
| Async Method | directories |
List the directory paths contained in the directory at path. |
| Async Method | directory |
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 | last |
Return the last-modification timestamp of the file at path. |
| Async Method | mime |
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. |
| Async Method | read |
Stream the contents of the file at path in chunks. |
| Method | relative |
Return the filesystem path relative to the application base path. |
| Async Method | set |
Change the visibility of the file at path. |
| Async Method | size |
Return the size in bytes of the file at path. |
| Async Method | temporary |
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 | write |
Write the chunks produced by stream to path. |
| Class Variable | __slots__ |
Declare the instance attribute slots reserved by this class. |
| Instance Variable | _base |
Application base path used for project-relative file paths. |
| Instance Variable | _base |
Base URL used to build public file URLs, or None when the disk does not expose URLs. |
| Instance Variable | _root |
Directory acting as the disk root. It is created when missing. |
Yield the direct children of the requested kind under base.
| Parameters | |
base:pathlib.Path | Absolute directory to inspect. |
wantbool | When True, yield directories; otherwise files. |
| Yields | |
pathlib.Path | Absolute path of each matching entry. |
Build a unique staging path for an atomic write.
| Parameters | |
absolute:pathlib.Path | Final absolute destination path. |
| Returns | |
pathlib.Path | Sibling path carrying a random infix, so concurrent writers never share a staging file, and still ending in .tmp so listings keep filtering it out. |
Yield every nested entry of the requested kind under base.
| Parameters | |
base:pathlib.Path | Absolute directory used as the traversal root. |
wantbool | When True, yield directories; otherwise files. |
| Yields | |
pathlib.Path | Absolute path of each matching entry. |
Return the absolute path for an already normalized path.
| Parameters | |
normalized:str | Canonical root-relative path. |
| Returns | |
pathlib.Path | Absolute path inside the disk root. |
Promote a finished temp file to its final destination.
| Parameters | |
tmp:pathlib.Path | Fully written temporary file. |
absolute:pathlib.Path | Final absolute destination path. |
visibility:str | None | Visibility to apply, or None to keep the OS default. |
| Returns | |
None | No return value. |
Copy source to target synchronously.
| Parameters | |
source:str | Canonical root-relative source path. |
target:str | Canonical root-relative destination path. |
| Returns | |
None | No return value. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the source file does not exist. |
Copy normalized to a local destination synchronously.
| Parameters | |
normalized:str | Canonical root-relative file path. |
destination:str | pathlib.Path | Local target file or existing directory. |
| Returns | |
pathlib.Path | Absolute local path of the downloaded file. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
Return the POSIX file mode for visibility.
| Parameters | |
visibility:str | Visibility level ('public' or 'private'). |
| Returns | |
int | Permission bits to apply to the file. |
| Raises | |
orionis.storage.exceptions.UnsupportedStorageOperationException | If visibility is not a supported level. |
Compute the content hash of normalized synchronously.
| Parameters | |
normalized:str | Canonical root-relative file path. |
algorithm:str | Any algorithm name accepted by hashlib.new. |
| Returns | |
str | Hexadecimal digest of the file contents. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
orionis.storage.exceptions.UnsupportedStorageOperationException | If algorithm is not available. |
Build a metadata snapshot for normalized synchronously.
| Parameters | |
normalized:str | Canonical root-relative file path. |
| Returns | |
orionis.storage.entities.FileInfo | Immutable metadata snapshot of the file. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
Self, root: Path, base_url: str | None = None, *, base_path: Path | None = None):
(source)
¶
Initialize the driver rooted at root.
| Parameters | |
root:pathlib.Path | Directory acting as the disk root. It is created when missing. |
basestr | None | Base URL used to build public file URLs, or None when the disk does not expose URLs. |
basepathlib.Path | None | Application base path used by relativePath(), or None when the driver is constructed without application context. |
| Returns | |
None | No return value. |
Move source to target synchronously.
| Parameters | |
source:str | Canonical root-relative source path. |
target:str | Canonical root-relative destination path. |
| Returns | |
None | No return value. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the source file does not exist. |
Open the file at normalized synchronously.
| Parameters | |
normalized:str | Canonical root-relative file path. |
mode:str | Binary mode to open the file with. |
| Returns | |
typing.BinaryIO | Open binary handle. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
OSError | If opening is denied or the filesystem reports another I/O failure. |
Open a temporary sibling file for writing synchronously.
| Parameters | |
tmp:pathlib.Path | Absolute path of the temporary file. |
visibility:str | None | Requested permissions applied when the staging file is created. |
| Returns | |
typing.BinaryIO | Open binary handle in write mode. |
Read the file at normalized synchronously.
| Parameters | |
normalized:str | Canonical root-relative file path. |
| Returns | |
bytes | Complete file contents. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
OSError | If reading is denied or the filesystem reports another I/O failure. |
Return the canonical relative path for absolute.
| Parameters | |
absolute:pathlib.Path | Absolute path inside the disk root. |
| Returns | |
str | Root-relative path using / as separator. |
Stat the file at normalized or raise when it is absent.
| Parameters | |
normalized:str | Canonical root-relative file path. |
| Returns | |
tuple[pathlib.Path, os.stat_result] | The absolute path and its os.stat_result. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the path does not reference an existing file. |
OSError | If metadata cannot be read for a reason other than absence. |
Return the absolute filesystem path of the file at path.
The file does not need to exist. Apply the same disk boundary validation used by content operations, including symbolic links.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
str | Absolute path using the operating system's separators. |
| Raises | |
orionis.storage.exceptions.StoragePathException | If path is invalid or escapes the disk root. |
Copy the file at source to target.
| Parameters | |
source:str | Root-relative path of the existing file. |
target:str | Root-relative destination path. |
| Returns | |
None | No return value. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the source file does not exist. |
Self, path: str = '', *, recursive: bool = False) -> list[ str]:
(source)
¶
Copy the file at path to a location on 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 file does not exist. |
Compute the content hash of the file at path.
| Parameters | |
path:str | Root-relative file path. |
algorithm:str | Any algorithm name accepted by hashlib.new. |
| Returns | |
str | Hexadecimal digest of the file contents. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
orionis.storage.exceptions.UnsupportedStorageOperationException | If algorithm is not available. |
Collect a metadata snapshot for the file at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
orionis.storage.entities.FileInfo | Immutable entity with size, MIME type, timestamps, hashes, visibility, and URL when available. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
Return the last-modification timestamp of the file at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
datetime.datetime | Timezone-aware modification timestamp (UTC). |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
Guess the MIME type of the file at path.
The guess is derived from the file extension and requires no disk access.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
str | None | MIME type, or None when it cannot be determined. |
Move the file at source to target.
| Parameters | |
source:str | Root-relative path of the existing file. |
target:str | Root-relative destination path. |
| Returns | |
None | No return value. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the source file does not exist. |
Open an asynchronous binary stream for the file at path.
| 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 file at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
bytes | Complete file contents. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
Self, path: str, chunk_size: int = _CHUNK_SIZE) -> AsyncIterator[ bytes]:
(source)
¶
Stream the contents of the file 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 file contents. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
Return the filesystem path relative to the application base path.
The file does not need to exist. Roots outside the project may require leading .. segments in the returned path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
str | Path from the application base path using / as separator. |
| Raises | |
orionis.storage.exceptions.UnsupportedStorageOperationException | If no application base path was supplied to the driver. |
orionis.storage.exceptions.StoragePathException | If path is invalid, escapes the disk root, or is on a different filesystem drive from the application base path. |
Change the visibility of the file 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 file does not exist. |
orionis.storage.exceptions.UnsupportedStorageOperationException | If visibility is not a supported level. |
Return the size in bytes of the file at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
int | File size in bytes. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
Build a signed, time-limited URL for the file at path.
The local driver cannot sign URLs, so this operation always fails.
| Parameters | |
path:str | Root-relative file path. |
expiresint | Lifetime of the URL in seconds. |
| Returns | |
str | Never returned by this driver. |
| Raises | |
orionis.storage.exceptions.UnsupportedStorageOperationException | Always, since local disks cannot sign URLs. |
Build the public URL for the file at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
str | Publicly accessible URL for the file. |
| Raises | |
orionis.storage.exceptions.UnsupportedStorageOperationException | If the disk has no base URL configured. |
Return the visibility of the file at path.
| Parameters | |
path:str | Root-relative file path. |
| Returns | |
str | 'public' or 'private'. |
| Raises | |
orionis.storage.exceptions.StorageFileNotFoundException | If the file does not exist. |
Self, path: str, contents: bytes | str, visibility: str | None = None):
(source)
¶
Write contents to path, replacing any existing file.
The write is atomic: data lands in a sibling temporary file that is renamed over the destination once complete.
| Parameters | |
path:str | Root-relative file path. |
contents:bytes | str | Data to persist. Strings are encoded as UTF-8. |
visibility:str | None | Visibility to apply, or None to keep the OS default. |
| Returns | |
None | No return value. |
Self, path: str, stream: AsyncIterable[ bytes], visibility: str | None = None):
(source)
¶
Write the chunks produced by stream to path.
Chunks are appended to a temporary file that atomically replaces the destination once the stream is exhausted, so a failed transfer never leaves a partial file behind.
| Parameters | |
path:str | Root-relative file path. |
stream:collections.abc.AsyncIterable[bytes] | Asynchronous byte-chunk producer. |
visibility:str | None | Visibility to apply, or None to keep the OS default. |
| Returns | |
None | No return value. |