hubvault.operations

Public commit operations for the hubvault repository API.

This module mirrors the high-level commit operation shape used by huggingface_hub so callers can describe write intent with familiar objects before passing them to hubvault.api.HubVaultApi.create_commit.

The module contains:

• CommitOperationAdd - Add or replace file content from bytes, a path, or a file object

• CommitOperationDelete - Delete a file or folder path

• CommitOperationCopy - Copy a file or subtree from another repo path

CommitOperationAdd

class hubvault.operations.CommitOperationAdd(path_in_repo: str, path_or_fileobj: str | Path | bytes | BinaryIO)

Add or replace a file in the repository.

The constructor follows the huggingface_hub public API shape by taking a single path_or_fileobj argument that may be local file bytes, a local filesystem path, or a binary file object.

Parameters:

• path_in_repo (str) – Target repo-relative path

• path_or_fileobj (Union[str, pathlib.Path, bytes, BinaryIO]) – File source expressed as a local path, bytes, or a binary file object

Raises:

ValueError – Raised when path_or_fileobj is not a supported source type or refers to a missing file.

Example:

>>> op = CommitOperationAdd("demo.txt", b"hello")
>>> op.path_in_repo
'demo.txt'

__post_init__() → None

Validate the add-operation source.

Returns:

None.

Return type:

None

Raises:

ValueError – Raised when path_or_fileobj is not a supported upload source or points to a missing local file.

Example:

>>> CommitOperationAdd("demo.txt", b"hello")
CommitOperationAdd(path_in_repo='demo.txt', path_or_fileobj=b'hello')

as_file() → Iterator[BinaryIO]

Yield a readable binary file object for the operation payload.

Returns:

Iterator yielding a binary file object

Return type:

Iterator[BinaryIO]

Example:

>>> op = CommitOperationAdd("demo.txt", b"hello")
>>> with op.as_file() as fileobj:
...     fileobj.read()
b'hello'

CommitOperationDelete

class hubvault.operations.CommitOperationDelete(path_in_repo: str, is_folder: bool | Literal['auto'] = 'auto')

Delete a file or folder from the repository.

Parameters:

• path_in_repo (str) – Repo-relative file or folder path

• is_folder (Union[bool, Literal["auto"]], optional) – Whether the delete targets a folder. When set to "auto", the operation treats a trailing "/" as a folder hint.

Raises:

ValueError – Raised when is_folder is not True, False, or "auto".

Example:

>>> CommitOperationDelete("folder/")
CommitOperationDelete(path_in_repo='folder/', is_folder=True)

__post_init__() → None

Normalize the folder-delete mode.

Returns:

None.

Return type:

None

Raises:

ValueError – Raised when is_folder has an unsupported value.

Example:

>>> CommitOperationDelete("folder/", is_folder="auto").is_folder
True

CommitOperationCopy

class hubvault.operations.CommitOperationCopy(src_path_in_repo: str, path_in_repo: str, src_revision: str | None = None)

Copy a file or subtree from another repo path.

Parameters:

• src_path_in_repo (str) – Source repo-relative path

• path_in_repo (str) – Destination repo-relative path

• src_revision (Optional[str], optional) – Optional source revision. When omitted, the current target revision head is used as the source snapshot.

Note

Private HF-internal constructor fields such as _src_oid and _dest_oid are intentionally not exposed here because they would be no-op compatibility placeholders in the local repository design.

Example:

>>> op = CommitOperationCopy("src/file.txt", "dst/file.txt", src_revision="main")
>>> op.src_revision
'main'