Drive#
- class nominal.experimental.drives.Drive(rid, id, description, workspace_rid, state, source, content_mutability, created_at, created_by_rid, subordinate_to_rid)#
Bases:
HasRid,RefreshableMixin[Drive]A workspace-scoped namespace for files.
- id: str | None#
Human-readable identifier, unique within the workspace, or
Nonefor a subordinate drive.
- state: DriveState#
- source: DriveSource#
Where the drive’s files come from.
- content_mutability: DriveMutability#
Whether the drive’s contents can be modified through Nominal.
- created_at: IntegralNanosecondsUTC | None#
- archive()#
Archive this drive, hiding it from listings that exclude archived drives.
- Returns:
This instance, updated.
- Return type:
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, orDriveBatch.put, then callDriveBatch.submit. Upload preparation remains separate from batch submission.- Return type:
- get_file(path, *, include_removed=False)#
Retrieve the file at a path in this drive.
- Parameters:
- Returns:
The file. This is a
ManagedDriveFilein a managed drive and aVirtualDriveFilein a provider-backed one.- Raises:
NominalNotFoundError – No file exists at that path.
- Return type:
- list_files(parent_path='', *, include_removed=False, recursive=False)#
List files and directories beneath a path in this drive.
- Parameters:
- 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:
- move_directory(source, destination)#
Move a directory and its active files within this drive.
- Parameters:
- 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.putandDriveBatch.submit, without changing this drive.- Parameters:
-
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:
FileNotFoundError –
local_pathdoes not exist.IsADirectoryError –
local_pathis a directory.ValueError –
local_pathis empty, or the destination has no filename or belongs to another drive.NominalFileStoreError – The drive is read-only.
- Return type:
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.putandDriveBatch.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:
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:
-
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_pathdoes not exist.IsADirectoryError –
local_pathis a directory.ValueError –
local_pathis empty,destinationis a path with no filename (for example it ends in/), ordestinationis 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:
Note
The service checks
destinationonly once the bytes have been uploaded, so a rejection arrives after the transfer. A file or revision passed asdestinationis 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")orio.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_objis open in text mode.ValueError –
file_objis not seekable or has nothing left to read,destinationis a path with no filename (for example it ends in/), ordestinationis 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:
Note
The service checks
destinationonly once the bytes have been uploaded, so a rejection arrives after the transfer. A file or revision passed asdestinationis 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.
- unarchive()#
Unarchive this drive, restoring it to listings.
- Returns:
This instance, updated.
- Return type:
Note
Unarchiving a drive requires organization-admin permissions.
- update(*, id=None, description=None)#
Update this drive’s details, refreshing it in place.
- Parameters:
- Returns:
This instance, updated.
- Raises:
NominalAlreadyExistsError – Another drive in the workspace already has
id.- Return type:
Note
Fields left as
Noneare unchanged. Updating a drive requires organization-admin permissions.