DriveFile#

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

Bases: DriveEntry, ABC

A file in a drive, managed or mirrored from an external provider.

Both kinds share these fields and can be downloaded. Only a ManagedDriveFile has a revision history and can be moved or removed; narrow with isinstance to reach those.

path#

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

size_bytes: int#
state: DriveFileState#
download_availability: DownloadAvailability#

Whether the observed content can be downloaded.

observed_at: IntegralNanosecondsUTC | None#

When the backend last observed 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