ManagedDriveFile#

class nominal.experimental.drives.ManagedDriveFile(path, size_bytes, state, download_availability, observed_at, rid, created_at, created_by_rid, current_revision_rid)#

Bases: DriveFile, HasRid, RefreshableMixin[LogicalFile]

A file stored in a Nominal-backed drive, with a stable RID and a revision history.

path#

Drive-relative path, with no leading or trailing slash.

size_bytes#
state#
download_availability#

Whether the observed content can be downloaded.

observed_at#

When the backend last observed this file.

rid: str#
created_at: IntegralNanosecondsUTC | None#
created_by_rid: str | None#
current_revision_rid: str | None#

RID of the revision currently at this path, if the file has one.

download(output_directory, *, part_size=DEFAULT_CHUNK_SIZE, num_retries=3)#

Download this file’s current content into a directory.

The download uses this snapshot’s revision reference. Nominal resolves virtual references and may fetch their content from the provider as it streams.

Parameters:
  • output_directory (Path | str)

    Directory to write into. The file is named after its path in the drive.

  • part_size (int)

    Size in bytes of each ranged download request.

  • num_retries (int)

    Retries per part.

Returns:

Path the file was written to.

Raises:
  • ValueError – The file’s name would not stay inside output_directory, for example because it contains a backslash.

  • NotADirectoryError – output_directory exists but is not a directory.

  • FileNotFoundError – output_directory does not exist.

  • FileExistsError – A file already exists at the destination.

  • NominalFileStoreError – This managed file has no current revision.

  • NominalNotFoundError – This file’s bytes are no longer retained.

  • requests.HTTPError – A virtual file’s provider can no longer serve the observed content, or can’t be reached.

Return type:

Path

move_to(destination)#

Move this file, refreshing it in place.

Parameters:

destination (str | ManagedDriveFile | DriveFileRevision)

Where to move the file. A path must be unoccupied; pass a file or revision to replace what is already there.

Returns:

This instance, updated.

Raises:
  • ValueError – destination is a file or revision from a different drive.

  • NominalFileStoreError – The move was rejected — for example the path is occupied, or this file’s revision is no longer current.

Return type:

Self

Note

File changes are not automatically replayed after transport errors, which can leave the outcome unknown. See Recover after a transport error before retrying.

refresh()#
Return type:

Self

remove()#

Remove this file, refreshing it in place.

Removal is soft: the file’s revisions remain, and any of them can be restored.

Returns:

This instance, updated.

Raises:

NominalFileStoreError – The removal was rejected — for example this file’s revision is no longer current.

Return type:

Self

Note

File changes are not automatically replayed after transport errors, which can leave the outcome unknown. See Recover after a transport error before retrying.

revisions()#

List this file’s revision history, in the order the backend returns it.

Returns:

Every revision of this file, including removal markers.

Return type:

Sequence[DriveFileRevision]