# VirtualDrive

## class nominal.experimental.drives.VirtualDrive(rid, id, description, workspace_rid, state, source, content_mutability, created_at, created_by_rid, subordinate_to_rid)

Bases: [`Drive`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.Drive.md#nominal.experimental.drives.Drive "nominal.experimental.drives.drive.Drive")

A read-only drive whose files are mirrored from an external provider.

Reads work exactly as they do on a managed drive. Writes raise [`NominalFileStoreError`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.NominalFileStoreError.md#nominal.experimental.drives.NominalFileStoreError "nominal.experimental.drives.NominalFileStoreError")
before any request is sent.

### rid

### id

Human-readable identifier, unique within the workspace, or `None` for a subordinate drive.

### description

Free-text description, or `None` when the drive has none.

### workspace_rid

### state

### source

Where the drive’s files come from.

### content_mutability

Whether the drive’s contents can be modified through Nominal.

### created_at

### created_by_rid

### subordinate_to_rid

Owning resource RID for a subordinate drive, otherwise `None`.

### archive()

Archive this drive, hiding it from listings that exclude archived drives.

Returns:
:   This instance, updated.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

> **Note**
>
> Archiving a drive requires organization-admin permissions.

### batch()

Create a single-use batch for this drive.

Queue operations with [`DriveBatch.move`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.move "nominal.experimental.drives.DriveBatch.move"), [`DriveBatch.remove`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.remove "nominal.experimental.drives.DriveBatch.remove"), [`DriveBatch.restore`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.restore "nominal.experimental.drives.DriveBatch.restore"),
[`DriveBatch.move_directory`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.move_directory "nominal.experimental.drives.DriveBatch.move_directory"), or [`DriveBatch.put`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.put "nominal.experimental.drives.DriveBatch.put"), then call [`DriveBatch.submit`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.submit "nominal.experimental.drives.DriveBatch.submit").
Upload preparation remains separate from batch submission.

Return type:
:   [*DriveBatch*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch "nominal.experimental.drives.changes.DriveBatch")

### get_file(path, *, include_removed=False)

Retrieve the file at a path in this drive.

Parameters:
:   - **path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Drive-relative path, with no leading or trailing slash and no `.` or
      `..` segments.
    - **include_removed** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      Also match a file that has been removed from this path.

Returns:
:   The file. This is a [`ManagedDriveFile`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.ManagedDriveFile.md#nominal.experimental.drives.ManagedDriveFile "nominal.experimental.drives.ManagedDriveFile") in a managed drive and a
    [`VirtualDriveFile`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.VirtualDriveFile.md#nominal.experimental.drives.VirtualDriveFile "nominal.experimental.drives.VirtualDriveFile") in a provider-backed one.

Raises:
:   [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – No file exists at that path.

Return type:
:   [*DriveFile*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveFile.md#nominal.experimental.drives.DriveFile "nominal.experimental.drives.file.DriveFile")

### list_files(parent_path='', *, include_removed=False, recursive=False)

List files and directories beneath a path in this drive.

Parameters:
:   - **parent_path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Directory to list. The default lists the drive root.
    - **include_removed** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      Include files that have been removed. Cannot be combined with `recursive`.
    - **recursive** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      List active files at every depth, without directory entries. Managed drives only.

Returns:
:   Every page in backend order. By default, entries are the immediate child
    directories and files. Recursive results contain active files at every depth.

Raises:
:   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – Recursive listing is requested for a virtual drive or with removed files.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*DriveEntry*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveEntry.md#nominal.experimental.drives.DriveEntry "nominal.experimental.drives.file.DriveEntry")]

### move_directory(source, destination)

Move a directory and its active files within this drive.

Parameters:
:   - **source** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Existing drive-relative directory path.
    - **destination** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Unoccupied directory path. Must not contain or sit inside `source`.

Raises:
:   [**NominalFileStoreError**](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.NominalFileStoreError.md#nominal.experimental.drives.NominalFileStoreError "nominal.experimental.drives.NominalFileStoreError") – The drive is read-only, the destination is occupied,
    the paths are invalid, or the move exceeds the service’s limits.

> **Note**
>
> Existing file snapshots retain their old paths until refreshed. The service
> returns no per-file details. A successful call means the move has been applied.
>
> File changes are not automatically replayed after transport errors, which can leave
> the outcome unknown. See [Recover after a transport error](https://dev.nominal.io/python/guides/drives/overview.md#drive-change-retries) before retrying.

### prepare_put_file(local_path, destination, *, chunk_size=DEFAULT_CHUNK_SIZE, max_workers=DEFAULT_NUM_WORKERS)

Upload a local file for a later [`DriveBatch.put`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.put "nominal.experimental.drives.DriveBatch.put") and [`DriveBatch.submit`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.submit "nominal.experimental.drives.DriveBatch.submit"), without changing this drive.

Parameters:
:   - **local_path** ([*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)"))

      Nonempty file on disk to upload.
    - **destination** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*ManagedDriveFile*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.ManagedDriveFile.md#nominal.experimental.drives.ManagedDriveFile "nominal.experimental.drives.file.ManagedDriveFile") *|* [*DriveFileRevision*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveFileRevision.md#nominal.experimental.drives.DriveFileRevision "nominal.experimental.drives.file.DriveFileRevision"))

      Unoccupied path or a file/revision whose current head must match.
    - **chunk_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

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

      Number of concurrent upload threads.

Returns:
:   A prepared put with a pinned destination precondition. Submit it to this drive.

Raises:
:   - [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError "(in Python v3.15)") – `local_path` does not exist.
    - [**IsADirectoryError**](https://docs.python.org/3/builtins/exceptions.html#IsADirectoryError "(in Python v3.15)") – `local_path` is a directory.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – `local_path` is empty, or the destination has no filename or
      belongs to another drive.
    - [**NominalFileStoreError**](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.NominalFileStoreError.md#nominal.experimental.drives.NominalFileStoreError "nominal.experimental.drives.NominalFileStoreError") – The drive is read-only.

Return type:
:   [*PreparedPut*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.PreparedPut.md#nominal.experimental.drives.PreparedPut "nominal.experimental.drives.changes.PreparedPut")

> **Note**
>
> The upload remains separate from the batch transaction. If preparation or the
> batch fails, already uploaded bytes are not rolled back. The destination is
> checked by the service only when the batch is applied. Input snapshots are not refreshed.

### prepare_put_file_obj(file_obj, destination, *, chunk_size=DEFAULT_CHUNK_SIZE, max_workers=DEFAULT_NUM_WORKERS)

Upload a binary stream for a later [`DriveBatch.put`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.put "nominal.experimental.drives.DriveBatch.put") and [`DriveBatch.submit`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveBatch.md#nominal.experimental.drives.DriveBatch.submit "nominal.experimental.drives.DriveBatch.submit"), without changing this drive.

Parameters:
:   - **file_obj** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      Seekable binary stream, read from its current position to its end.
    - **destination** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*ManagedDriveFile*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.ManagedDriveFile.md#nominal.experimental.drives.ManagedDriveFile "nominal.experimental.drives.file.ManagedDriveFile") *|* [*DriveFileRevision*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveFileRevision.md#nominal.experimental.drives.DriveFileRevision "nominal.experimental.drives.file.DriveFileRevision"))

      Unoccupied path or a file/revision whose current head must match.
    - **chunk_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

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

      Number of concurrent upload threads.

Returns:
:   A prepared put with a pinned destination precondition. The caller may close
    the stream after this method returns.

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – The stream is open in text mode.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – The stream is not seekable or has no bytes left, or the destination
      has no filename or belongs to another drive.
    - [**NominalFileStoreError**](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.NominalFileStoreError.md#nominal.experimental.drives.NominalFileStoreError "nominal.experimental.drives.NominalFileStoreError") – The drive is read-only.

Return type:
:   [*PreparedPut*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.PreparedPut.md#nominal.experimental.drives.PreparedPut "nominal.experimental.drives.changes.PreparedPut")

> **Note**
>
> Uploaded bytes are outside the batch transaction and are not rolled back by
> an aborted batch. Destination conflicts are reported only when applying the batch.

### put_file(local_path, destination, *, chunk_size=DEFAULT_CHUNK_SIZE, max_workers=DEFAULT_NUM_WORKERS)

Upload a local file into this drive, as a new file or a new version of an existing one.

Parameters:
:   - **local_path** ([*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)"))

      File on disk to upload.
    - **destination** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*ManagedDriveFile*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.ManagedDriveFile.md#nominal.experimental.drives.ManagedDriveFile "nominal.experimental.drives.file.ManagedDriveFile") *|* [*DriveFileRevision*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveFileRevision.md#nominal.experimental.drives.DriveFileRevision "nominal.experimental.drives.file.DriveFileRevision"))

      Where the upload goes. A path creates a file there and must be
      unoccupied; a file or revision adds a new version to that file, which must
      still be at that revision.
    - **chunk_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

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

      Number of threads uploading parts concurrently.

Returns:
:   The file as it now exists in the drive.

Raises:
:   - [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError "(in Python v3.15)") – `local_path` does not exist.
    - [**IsADirectoryError**](https://docs.python.org/3/builtins/exceptions.html#IsADirectoryError "(in Python v3.15)") – `local_path` is a directory.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – `local_path` is empty, `destination` is a path with no filename
      (for example it ends in `/`), or `destination` is from a different drive.
    - [**NominalFileStoreError**](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.NominalFileStoreError.md#nominal.experimental.drives.NominalFileStoreError "nominal.experimental.drives.NominalFileStoreError") – This drive is read-only, or the service rejected the new
      content — for example the path is occupied, or the file has moved on.

Return type:
:   [*ManagedDriveFile*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.ManagedDriveFile.md#nominal.experimental.drives.ManagedDriveFile "nominal.experimental.drives.file.ManagedDriveFile")

> **Note**
>
> The service checks `destination` only once the bytes have been uploaded, so a
> rejection arrives after the transfer. A file or revision passed as `destination`
> is not refreshed; use the returned file.
>
> File changes are not automatically replayed after transport errors, which can leave
> the outcome unknown. See [Recover after a transport error](https://dev.nominal.io/python/guides/drives/overview.md#drive-change-retries) before retrying.

### put_file_obj(file_obj, destination, *, chunk_size=DEFAULT_CHUNK_SIZE, max_workers=DEFAULT_NUM_WORKERS)

Upload the contents of a binary file-like object into this drive.

The object is read from its current position to its end. It must be seekable, because
empty input is rejected before anything is uploaded.

Parameters:
:   - **file_obj** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      Seekable binary file-like object, e.g. `open(path, "rb")` or [`io.BytesIO`](https://docs.python.org/3/library/io.html#io.BytesIO "(in Python v3.15)").
    - **destination** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*ManagedDriveFile*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.ManagedDriveFile.md#nominal.experimental.drives.ManagedDriveFile "nominal.experimental.drives.file.ManagedDriveFile") *|* [*DriveFileRevision*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveFileRevision.md#nominal.experimental.drives.DriveFileRevision "nominal.experimental.drives.file.DriveFileRevision"))

      Where the upload goes. A path creates a file there and must be
      unoccupied; a file or revision adds a new version to that file, which must
      still be at that revision.
    - **chunk_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

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

      Number of threads uploading parts concurrently.

Returns:
:   The file as it now exists in the drive.

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – `file_obj` is open in text mode.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – `file_obj` is not seekable or has nothing left to read,
      `destination` is a path with no filename (for example it ends in `/`), or
      `destination` is from a different drive.
    - [**NominalFileStoreError**](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.NominalFileStoreError.md#nominal.experimental.drives.NominalFileStoreError "nominal.experimental.drives.NominalFileStoreError") – This drive is read-only, or the service rejected the new
      content — for example the path is occupied, or the file has moved on.

Return type:
:   [*ManagedDriveFile*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.ManagedDriveFile.md#nominal.experimental.drives.ManagedDriveFile "nominal.experimental.drives.file.ManagedDriveFile")

> **Note**
>
> The service checks `destination` only once the bytes have been uploaded, so a
> rejection arrives after the transfer. A file or revision passed as `destination`
> is not refreshed; use the returned file.
>
> File changes are not automatically replayed after transport errors, which can leave
> the outcome unknown. See [Recover after a transport error](https://dev.nominal.io/python/guides/drives/overview.md#drive-change-retries) before retrying.

### refresh()

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### status()

Probe the backing provider and report its current connectivity.

Returns:
:   The provider’s state, a human-readable message, and when it was last reached.

Return type:
:   [*VirtualDriveStatus*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.VirtualDriveStatus.md#nominal.experimental.drives.VirtualDriveStatus "nominal.experimental.drives.drive.VirtualDriveStatus")

### unarchive()

Unarchive this drive, restoring it to listings.

Returns:
:   This instance, updated.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

> **Note**
>
> Unarchiving a drive requires organization-admin permissions.

### update(*, id=None, description=None)

Update this drive’s details, refreshing it in place.

Parameters:
:   - **id** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      New identifier for the drive, unique within the workspace. Up to 100 letters,
      digits, `.`, `-`, and `_`, starting with a letter or digit; ids starting
      with `nominal.` in any casing are reserved.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      New description for the drive. An empty string clears it.

Returns:
:   This instance, updated.

Raises:
:   [**NominalAlreadyExistsError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalAlreadyExistsError.md#nominal.exceptions.NominalAlreadyExistsError "nominal.exceptions.NominalAlreadyExistsError") – Another drive in the workspace already has `id`.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

> **Note**
>
> Fields left as `None` are unchanged. Updating a drive requires
> organization-admin permissions.
