orionis.storage.File

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

class documentation

class File(IFile): (source)

Constructor: File(driver, path)

View In Hierarchy

Represent a single file on a storage disk.

The object encapsulates its canonical path and the driver of the disk it belongs to. It never knows which physical medium backs it: every operation is delegated to the driver.

Method	`__init__`	Initialize the file with its driver and canonical path.
Async Method	`copyTo`	Copy the file to target on the same disk.
Async Method	`delete`	Delete the file from its disk.
Async Method	`download`	Copy the file to a location on the local filesystem.
Async Method	`exists`	Check whether the file exists on its disk.
Async Method	`hash`	Compute the content hash of the file.
Async Method	`info`	Collect a metadata snapshot for the file.
Async Method	`lastModified`	Return the last-modification timestamp of the file.
Async Method	`mimeType`	Guess the MIME type of the file.
Async Method	`moveTo`	Move the file to target on the same disk.
Method	`open`	Open an asynchronous binary stream over the file.
Method	`path`	Return the canonical root-relative path of the file.
Async Method	`read`	Read the full contents of the file.
Method	`readStream`	Stream the contents of the file in chunks.
Async Method	`rename`	Rename the file within its current directory.
Async Method	`setVisibility`	Change the visibility of the file.
Async Method	`size`	Return the size of the file in bytes.
Async Method	`temporaryUrl`	Build a signed, time-limited URL for the file.
Async Method	`url`	Build the public URL of the file.
Async Method	`visibility`	Return the visibility of the file.
Async Method	`write`	Write contents to the file, replacing existing data.
Async Method	`writeStream`	Write the chunks produced by stream to the file.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_driver`	Undocumented
Instance Variable	`_path`	Undocumented

def __init__(self, driver: IStorageDriver, path: str): (source) ¶

Initialize the file with its driver and canonical path.

Parameters
driver:`IStorageDriver`	Driver of the disk that owns the file.
path:`str`	Root-relative file path; normalized on ingestion.

Returns
`None`	Undocumented

Raises
`StoragePathException`	If path is invalid or resolves to the disk root.

async def copyTo(self, target: str) -> IFile: (source) ¶

overrides orionis.storage.contracts.IFile.copyTo

Copy the file to target on the same disk.

Parameters
target:`str`	Root-relative destination path.

Returns
`IFile`	A new file object pointing at the copy.

Raises
`StorageFileNotFoundException`	If the source file does not exist.

async def delete(self) -> bool: (source) ¶

overrides orionis.storage.contracts.IFile.delete

Delete the file from its disk.

Returns
`bool`	`True` if the file existed and was removed.

async def download(self, destination: str | Path) -> Path: (source) ¶

overrides orionis.storage.contracts.IFile.download

Copy the file to a location on the local filesystem.

Parameters
destination:`str \| Path`	Local target. When it points to an existing directory the file keeps its original name inside that directory.

Returns
`Path`	Absolute local path of the downloaded file.

Raises
`StorageFileNotFoundException`	If the file does not exist.

async def exists(self) -> bool: (source) ¶

overrides orionis.storage.contracts.IFile.exists

Check whether the file exists on its disk.

Returns
`bool`	`True` if the file exists.

async def hash(self, algorithm: str = 'sha256') -> str: (source) ¶

overrides orionis.storage.contracts.IFile.hash

Compute the content hash of the file.

Parameters
algorithm:`str`	Any algorithm name accepted by `hashlib.new`.

Returns
`str`	Hexadecimal digest of the file contents.

Raises
`StorageFileNotFoundException`	If the file does not exist.

async def info(self) -> FileInfo: (source) ¶

overrides orionis.storage.contracts.IFile.info

Collect a metadata snapshot for the file.

Returns
`FileInfo`	Immutable entity with size, MIME type, timestamps, hashes, visibility, and URL when available.

Raises
`StorageFileNotFoundException`	If the file does not exist.

async def lastModified(self) -> datetime: (source) ¶

overrides orionis.storage.contracts.IFile.lastModified

Return the last-modification timestamp of the file.

Returns
`datetime`	Timezone-aware modification timestamp (UTC).

Raises
`StorageFileNotFoundException`	If the file does not exist.

async def mimeType(self) -> str | None: (source) ¶

overrides orionis.storage.contracts.IFile.mimeType

Guess the MIME type of the file.

Returns
`str \| None`	MIME type, or `None` when it cannot be determined.

async def moveTo(self, target: str) -> IFile: (source) ¶

overrides orionis.storage.contracts.IFile.moveTo

Move the file to target on the same disk.

The current object keeps pointing at the old path; use the returned object to keep working with the moved file.

Parameters
target:`str`	Root-relative destination path.

Returns
`IFile`	A new file object pointing at the moved file.

Raises
`StorageFileNotFoundException`	If the source file does not exist.

def open(self, mode: str = 'rb') -> IStorageStream: (source) ¶

overrides orionis.storage.contracts.IFile.open

Open an asynchronous binary stream over the file.

Parameters
mode:`str`	Binary mode: `'rb'`, `'wb'`, `'ab'`, `'rb+'`, `'wb+'`, or `'ab+'`.

Returns
`IStorageStream`	Lazily opened stream; use it as an async context manager.

Raises
`UnsupportedStorageOperationException`	If mode is not a supported binary mode.

def path(self) -> str: (source) ¶

overrides orionis.storage.contracts.IFile.path

Return the canonical root-relative path of the file.

Returns
`str`	Normalized path relative to the disk root.

async def read(self) -> bytes: (source) ¶

overrides orionis.storage.contracts.IFile.read

Read the full contents of the file.

Returns
`bytes`	Complete file contents.

Raises
`StorageFileNotFoundException`	If the file does not exist.

def readStream(self, chunk_size: int = 65536) -> AsyncIterator[bytes]: (source) ¶

overrides orionis.storage.contracts.IFile.readStream

Stream the contents of the file in chunks.

Parameters
chunk_size:`int`	Maximum number of bytes per yielded chunk.

Returns
`AsyncIterator[bytes]`	Asynchronous iterator yielding consecutive chunks.

Raises
`StorageFileNotFoundException`	If the file does not exist.

async def rename(self, name: str) -> IFile: (source) ¶

overrides orionis.storage.contracts.IFile.rename

Rename the file within its current directory.

Parameters
name:`str`	New file name without any directory separator.

Returns
`IFile`	A new file object pointing at the renamed file.

Raises
`StoragePathException`	If name is empty or contains a directory separator.
`StorageFileNotFoundException`	If the source file does not exist.

async def setVisibility(self, visibility: str) -> IFile: (source) ¶

overrides orionis.storage.contracts.IFile.setVisibility

Change the visibility of the file.

Parameters
visibility:`str`	Target visibility (`'public'` or `'private'`).

Returns
`IFile`	The file itself, enabling fluent chaining.

Raises
`StorageFileNotFoundException`	If the file does not exist.

async def size(self) -> int: (source) ¶

overrides orionis.storage.contracts.IFile.size

Return the size of the file in bytes.

Returns
`int`	File size in bytes.

Raises
`StorageFileNotFoundException`	If the file does not exist.

async def temporaryUrl(self, expires_in: int = 3600) -> str: (source) ¶

overrides orionis.storage.contracts.IFile.temporaryUrl

Build a signed, time-limited URL for the file.

Parameters
expires_in:`int`	Lifetime of the URL in seconds.

Returns
`str`	Temporary URL valid for expires_in seconds.

Raises
`UnsupportedStorageOperationException`	If the driver does not support temporary URLs.

async def url(self) -> str: (source) ¶

overrides orionis.storage.contracts.IFile.url

Build the public URL of the file.

Returns
`str`	Publicly accessible URL.

Raises
`UnsupportedStorageOperationException`	If the disk does not expose public URLs.

async def visibility(self) -> str: (source) ¶

overrides orionis.storage.contracts.IFile.visibility

Return the visibility of the file.

Returns
`str`	`'public'` or `'private'`.

Raises
`StorageFileNotFoundException`	If the file does not exist.

async def write(self, contents: bytes | str, visibility: str | None = None) -> IFile: (source) ¶

overrides orionis.storage.contracts.IFile.write

Write contents to the file, replacing existing data.

Parameters
contents:`bytes \| str`	Data to persist. Strings are encoded as UTF-8.
visibility:`str \| None`	Visibility to apply, or `None` for the medium default.

Returns
`IFile`	The file itself, enabling fluent chaining.

async def writeStream(self, stream: AsyncIterable[bytes], visibility: str | None = None) -> IFile: (source) ¶

overrides orionis.storage.contracts.IFile.writeStream

Write the chunks produced by stream to the file.

Parameters
stream:`AsyncIterable[bytes]`	Asynchronous byte-chunk producer.
visibility:`str \| None`	Visibility to apply, or `None` for the medium default.

Returns
`IFile`	The file itself, enabling fluent chaining.

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.storage.contracts.IFile.__slots__

Undocumented

_driver = (source) ¶

Undocumented

_path = (source) ¶

Undocumented