# DriveBatch

## class nominal.experimental.drives.DriveBatch(drive)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

Build an ordered batch for one drive, then submit it once.

Obtain a batch with [`Drive.batch`](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.Drive.md#nominal.experimental.drives.Drive.batch "nominal.experimental.drives.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

```python
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*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.ManagedDriveFile.md#nominal.experimental.drives.ManagedDriveFile "nominal.experimental.drives.file.ManagedDriveFile"))

      File in this drive to move.
    - **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 to replace in this drive.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – The source belongs to another drive. Destination ownership
      is checked at submission, before any request.
    - [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – The batch was already submitted.

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

### move_directory(source, destination)

Queue a directory move and return this batch.

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

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

      Unoccupied directory path, neither inside nor containing the source.

Raises:
:   [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – The batch was already submitted.

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

> **Note**
>
> A successful directory move returns no per-file details.

### put(prepared)

Queue an already uploaded file and return this batch.

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

    Upload from this drive’s `prepare_put_file` or
    `prepare_put_file_obj`. Its destination precondition stays pinned.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – The upload belongs to another drive.
    - [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – The batch was already submitted.

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

### remove(source)

Queue removal of a file, retaining its history, and return this batch.

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

    File in this drive to remove.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – The source belongs to another drive.
    - [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – The batch was already submitted.

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

### restore(revision, destination)

Queue restoration of historical content and return this batch.

Parameters:
:   - **revision** ([*DriveFileRevision*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DriveFileRevision.md#nominal.experimental.drives.DriveFileRevision "nominal.experimental.drives.file.DriveFileRevision"))

      Historical revision in this drive.
    - **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 to replace in this drive.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – The revision belongs to another drive. Destination ownership
      is checked at submission, before any request.
    - [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – The batch was already submitted.

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

### submit(*, failure_policy=FailurePolicy.CONTINUE)

Submit the queued changes in one request, preserving their order.

Parameters:
:   **failure_policy** ([*FailurePolicy*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.FailurePolicy.md#nominal.experimental.drives.FailurePolicy "nominal.experimental.drives.changes.FailurePolicy"))

    `CONTINUE` applies changes independently (up to 1,000).
    `ABORT` applies 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**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – The batch exceeds its limit or a destination 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 or a file has no current revision.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – The request failed; a transport error can leave its outcome unknown.
    - [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – The batch was already submitted.

Return type:
:   [*list*](https://docs.python.org/3/builtins/stdtypes.html#list "(in Python v3.15)")[[*FileChangeSuccess*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.FileChangeSuccess.md#nominal.experimental.drives.FileChangeSuccess "nominal.experimental.drives.changes.FileChangeSuccess") | [*DirectoryMoveSuccess*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.DirectoryMoveSuccess.md#nominal.experimental.drives.DirectoryMoveSuccess "nominal.experimental.drives.changes.DirectoryMoveSuccess") | [*FileChangeFailure*](https://dev.nominal.io/python/ref/generated/nominal.experimental.drives.FileChangeFailure.md#nominal.experimental.drives.FileChangeFailure "nominal.experimental.drives.changes.FileChangeFailure")]

> **Note**
>
> Submission consumes the batch even if it fails. Do not blindly recreate and
> retry it: see [Recover after a transport error](https://dev.nominal.io/python/guides/drives/overview.md#drive-change-retries) 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 have `BATCH_FAILURE`. Uploaded bytes are outside the transaction.
