# VirtualDriveFile

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

Bases: [`DriveFile`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveFile.md#nominal.experimental.drives.DriveFile "nominal.experimental.drives.file.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*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Directory to write into. The file is named after its path in
      the drive.
    - **part_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Size in bytes of each ranged download request.
    - **num_retries** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Retries per part.

Returns:
:   Path the file was written to.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – The file’s name would not stay inside `output_directory`, for
      example because it contains a backslash.
    - [**NotADirectoryError**](https://docs.python.org/3/builtins/exceptions.html#NotADirectoryError "(in Python v3.15)") – `output_directory` exists but is not a directory.
    - [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError "(in Python v3.15)") – `output_directory` does not exist.
    - [**FileExistsError**](https://docs.python.org/3/builtins/exceptions.html#FileExistsError "(in Python v3.15)") – A file already exists at the destination.
    - [**NominalFileStoreError**](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.NominalFileStoreError.md#nominal.experimental.drives.NominalFileStoreError "nominal.experimental.drives.NominalFileStoreError") – This managed file has no current revision.
    - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.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*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)")

### 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*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")
