DriveBatch#
- class nominal.experimental.drives.DriveBatch(drive)#
Bases:
objectBuild an ordered batch for one drive, then submit it once.
Obtain a batch with
Drive.batch. Adding operations does not make requests. File revision preconditions are read from the supplied snapshots at submission; prepared puts retain their preparation-time preconditions. Input snapshots are not refreshed by submission. Use the returned files or refresh them explicitly.Bind a batch to its drive.
Example
batch = drive.batch() batch.move(file, "archive/readings.csv") results = batch.submit()
- move(source, destination)#
Queue a file move and return this batch.
- Parameters:
source (ManagedDriveFile)
File in this drive to move.
destination (str | ManagedDriveFile | DriveFileRevision)
Unoccupied path, or a file/revision to replace in this drive.
- Raises:
ValueError – The source belongs to another drive. Destination ownership is checked at submission, before any request.
RuntimeError – The batch was already submitted.
- Return type:
- move_directory(source, destination)#
Queue a directory move and return this batch.
- Parameters:
- Raises:
RuntimeError – The batch was already submitted.
- Return type:
Note
A successful directory move returns no per-file details.
- put(prepared)#
Queue an already uploaded file and return this batch.
- Parameters:
prepared (PreparedPut)
Upload from this drive’s
prepare_put_fileorprepare_put_file_obj. Its destination precondition stays pinned.- Raises:
ValueError – The upload belongs to another drive.
RuntimeError – The batch was already submitted.
- Return type:
- remove(source)#
Queue removal of a file, retaining its history, and return this batch.
- Parameters:
source (ManagedDriveFile)
File in this drive to remove.
- Raises:
ValueError – The source belongs to another drive.
RuntimeError – The batch was already submitted.
- Return type:
- restore(revision, destination)#
Queue restoration of historical content and return this batch.
- Parameters:
revision (DriveFileRevision)
Historical revision in this drive.
destination (str | ManagedDriveFile | DriveFileRevision)
Unoccupied path, or a file/revision to replace in this drive.
- Raises:
ValueError – The revision belongs to another drive. Destination ownership is checked at submission, before any request.
RuntimeError – The batch was already submitted.
- Return type:
- submit(*, failure_policy=FailurePolicy.CONTINUE)#
Submit the queued changes in one request, preserving their order.
- Parameters:
failure_policy (FailurePolicy)
CONTINUEapplies changes independently (up to 1,000).ABORTapplies all changes or none (up to 100). Batches are not split.- Returns:
One typed success or failure per operation, in order. Per-change failures are returned rather than raised. An empty batch returns an empty list.
- Raises:
ValueError – The batch exceeds its limit or a destination belongs to another drive.
NominalFileStoreError – The drive is read-only or a file has no current revision.
NominalError – The request failed; a transport error can leave its outcome unknown.
RuntimeError – The batch was already submitted.
- Return type:
list[FileChangeSuccess | DirectoryMoveSuccess | FileChangeFailure]
Note
Submission consumes the batch even if it fails. Do not blindly recreate and retry it: see Recover after a transport error to reconcile uncertain outcomes. Earlier changes are visible to later changes, but all revision preconditions are encoded before the request. Two changes to the same file can therefore conflict. Under
ABORT, the failing change has its own error and the other results haveBATCH_FAILURE. Uploaded bytes are outside the transaction.