VirtualDriveFile#

class nominal.experimental.drives.VirtualDriveFile(path, size_bytes, state, download_availability, observed_at, provider)#

Bases: DriveFile

A file mirrored from an external provider, pinned by content rather than by RID.

It has no revision history and cannot be moved or removed through Nominal.

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.

provider: DriveSource#

Which external provider backs this file.

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

resolve()#

Pin this file’s currently-observed content and return its revision RID.

Resolving is durable: the same observed content always resolves to the same RID, even after the file later changes upstream. Resolving does not copy its bytes or guarantee they remain available from the provider.

Returns:

RID of the pinned revision.

Return type:

str