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

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 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

Note

Archiving a drive requires organization-admin permissions.

batch()#

Create a single-use batch for this drive.

Queue operations with DriveBatch.move, DriveBatch.remove, DriveBatch.restore, DriveBatch.move_directory, or DriveBatch.put, then call DriveBatch.submit. Upload preparation remains separate from batch submission.

Return type:

DriveBatch

get_file(path, *, include_removed=False)#

Retrieve the file at a path in this drive.

Parameters:
  • path (str)

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

  • include_removed (bool)

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

Returns:

The file. This is a ManagedDriveFile in a managed drive and a VirtualDriveFile in a provider-backed one.

Raises:

NominalNotFoundError – No file exists at that path.

Return type:

DriveFile

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

List files and directories beneath a path in this drive.

Parameters:
  • parent_path (str)

    Directory to list. The default lists the drive root.

  • include_removed (bool)

    Include files that have been removed. Cannot be combined with recursive.

  • recursive (bool)

    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 – Recursive listing is requested for a virtual drive or with removed files.

Return type:

Sequence[DriveEntry]

move_directory(source, destination)#

Move a directory and its active files within this drive.

Parameters:
  • source (str)

    Existing drive-relative directory path.

  • destination (str)

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

Raises:

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 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 and DriveBatch.submit, without changing this drive.

Parameters:
  • local_path (Path | str)

    Nonempty file on disk to upload.

  • destination (str | ManagedDriveFile | DriveFileRevision)

    Unoccupied path or a file/revision whose current head must match.

  • chunk_size (int)

    Size in bytes of each upload part.

  • max_workers (int)

    Number of concurrent upload threads.

Returns:

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

Raises:
Return type:

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 and DriveBatch.submit, without changing this drive.

Parameters:
  • file_obj (BinaryIO)

    Seekable binary stream, read from its current position to its end.

  • destination (str | ManagedDriveFile | DriveFileRevision)

    Unoccupied path or a file/revision whose current head must match.

  • chunk_size (int)

    Size in bytes of each upload part.

  • max_workers (int)

    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 – The stream is open in text mode.

  • ValueError – The stream is not seekable or has no bytes left, or the destination has no filename or belongs to another drive.

  • NominalFileStoreError – The drive is read-only.

Return type:

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 | str)

    File on disk to upload.

  • destination (str | ManagedDriveFile | 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)

    Size in bytes of each upload part.

  • max_workers (int)

    Number of threads uploading parts concurrently.

Returns:

The file as it now exists in the drive.

Raises:
  • FileNotFoundError – local_path does not exist.

  • IsADirectoryError – local_path is a directory.

  • ValueError – local_path is empty, destination is a path with no filename (for example it ends in /), or destination is from a different drive.

  • 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

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 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)

    Seekable binary file-like object, e.g. open(path, "rb") or io.BytesIO.

  • destination (str | ManagedDriveFile | 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)

    Size in bytes of each upload part.

  • max_workers (int)

    Number of threads uploading parts concurrently.

Returns:

The file as it now exists in the drive.

Raises:
  • TypeError – file_obj is open in text mode.

  • ValueError – 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 – 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

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 before retrying.

refresh()#
Return type:

Self

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

unarchive()#

Unarchive this drive, restoring it to listings.

Returns:

This instance, updated.

Return type:

Self

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 | 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 | None)

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

Returns:

This instance, updated.

Raises:

NominalAlreadyExistsError – Another drive in the workspace already has id.

Return type:

Self

Note

Fields left as None are unchanged. Updating a drive requires organization-admin permissions.