hubvault.remote.api

Public remote API surface for hubvault.remote.

This module defines the public HTTP-backed client that mirrors the supported local hubvault.api.HubVaultApi read, write, and maintenance APIs.

The module contains:

FAST_UPLOAD_CHUNK_THRESHOLD

hubvault.remote.api.FAST_UPLOAD_CHUNK_THRESHOLD = 1048576

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

HubVaultRemoteAPI

hubvault.remote.api.HubVaultRemoteAPI = <class 'hubvault.remote.api.HubVaultRemoteApi'>

Remote API client aligned with hubvault.api.HubVaultApi.

The remote client intentionally mirrors the local API naming for common read and write paths so callers can switch between embedded and HTTP-backed repositories with minimal adaptation. Optional HTTP dependencies remain lazy; importing this class does not require the remote extra until a real transport call is attempted.

Parameters:

  • base_url (str) – Base URL of the remote server

  • token (Optional[str]) – Optional bearer token used for authenticated requests

  • revision (str) – Default revision used by read APIs

  • timeout (float) – Default request timeout in seconds

  • cache_dir (Optional[Union[str, os.PathLike[str]]]) – Optional client-local cache root override

Example:

>>> api = HubVaultRemoteApi("https://example.com/api", token="secret", revision="main")
>>> api.base_url
'https://example.com/api'

HubVaultRemoteApi

class hubvault.remote.api.HubVaultRemoteApi(base_url: str, token: str | None = None, revision: str = 'main', timeout: float = 30.0, cache_dir: str | PathLike | None = None)[source]

Remote API client aligned with hubvault.api.HubVaultApi.

The remote client intentionally mirrors the local API naming for common read and write paths so callers can switch between embedded and HTTP-backed repositories with minimal adaptation. Optional HTTP dependencies remain lazy; importing this class does not require the remote extra until a real transport call is attempted.

Parameters:

  • base_url (str) – Base URL of the remote server

  • token (Optional[str]) – Optional bearer token used for authenticated requests

  • revision (str) – Default revision used by read APIs

  • timeout (float) – Default request timeout in seconds

  • cache_dir (Optional[Union[str, os.PathLike[str]]]) – Optional client-local cache root override

Example:

>>> api = HubVaultRemoteApi("https://example.com/api", token="secret", revision="main")
>>> api.base_url
'https://example.com/api'
__init__(base_url: str, token: str | None = None, revision: str = 'main', timeout: float = 30.0, cache_dir: str | PathLike | None = None) → None[source]

Build one remote API client shell.

Parameters:

  • base_url (str) – Base URL of the remote server

  • token (Optional[str]) – Optional bearer token used for authenticated requests

  • revision (str) – Default revision used by read APIs

  • timeout (float) – Default request timeout in seconds

  • cache_dir (Optional[Union[str, os.PathLike]]) – Optional client-local cache root override

Returns:

None.

Return type:

None

build_client()[source]

Build the underlying HTTP client lazily.

Returns:

Configured HTTP transport client

Return type:

httpx.Client

Raises:

hubvault.optional.MissingOptionalDependencyError – Raised when the remote extra is not installed.

create_branch(*, branch: str, revision: str | None = None, exist_ok: bool = False) → None[source]

Create one remote branch.

Parameters:

  • branch (str) – Branch name to create

  • revision (Optional[str]) – Optional start-point revision

  • exist_ok (bool) – Whether an existing branch may be reused

Returns:

None.

Return type:

None

create_commit(operations: Sequence[object] = (), *, commit_message: str, commit_description: str | None = None, revision: str | None = None, parent_commit: str | None = None, progress_callback: Callable[[int, int], None] | None = None, show_progress: bool = False)[source]

Create one remote commit through the planned upload protocol.

Parameters:

  • operations (Sequence[object]) – Public commit operations to apply

  • commit_message (str) – Commit summary/title

  • commit_description (Optional[str]) – Optional commit description/body

  • revision (Optional[str]) – Optional target branch override

  • parent_commit (Optional[str]) – Optional optimistic-concurrency base head

  • progress_callback (Optional[Callable[[int, int], None]]) – Optional callback receiving (sent, total) upload-byte updates for streamed file/chunk parts

  • show_progress (bool) – Whether to show a tqdm progress bar when no explicit callback is provided

Returns:

Commit metadata for the created commit

Return type:

hubvault.models.CommitInfo

create_tag(*, tag: str, tag_message: str | None = None, revision: str | None = None, exist_ok: bool = False) → None[source]

Create one remote lightweight tag.

Parameters:

  • tag (str) – Tag name to create

  • tag_message (Optional[str]) – Optional reflog message for the new tag

  • revision (Optional[str]) – Optional start-point revision

  • exist_ok (bool) – Whether an existing tag may be reused

Returns:

None.

Return type:

None

delete_branch(*, branch: str) → None[source]

Delete one remote branch.

Parameters:

branch (str) – Branch name to delete

Returns:

None.

Return type:

None

delete_file(path_in_repo: str, *, revision: str | None = None, commit_message: str | None = None, commit_description: str | None = None, parent_commit: str | None = None)[source]

Delete one remote file through the public write API.

Parameters:

  • path_in_repo (str) – Repo-relative file path

  • revision (Optional[str]) – Optional target branch override

  • commit_message (Optional[str]) – Optional commit summary

  • commit_description (Optional[str]) – Optional commit description/body

  • parent_commit (Optional[str]) – Optional optimistic-concurrency base head

Returns:

Commit metadata for the created commit

Return type:

hubvault.models.CommitInfo

delete_folder(path_in_repo: str, *, revision: str | None = None, commit_message: str | None = None, commit_description: str | None = None, parent_commit: str | None = None)[source]

Delete one remote folder subtree through the public write API.

Parameters:

  • path_in_repo (str) – Repo-relative folder path

  • revision (Optional[str]) – Optional target branch override

  • commit_message (Optional[str]) – Optional commit summary

  • commit_description (Optional[str]) – Optional commit description/body

  • parent_commit (Optional[str]) – Optional optimistic-concurrency base head

Returns:

Commit metadata for the created commit

Return type:

hubvault.models.CommitInfo

delete_tag(*, tag: str) → None[source]

Delete one remote lightweight tag.

Parameters:

tag (str) – Tag name to delete

Returns:

None.

Return type:

None

full_verify()[source]

Run the remote full verification pass.

Returns:

Verification report

Return type:

hubvault.models.VerifyReport

gc(*, dry_run: bool = False, prune_cache: bool = True)[source]

Run one remote GC pass.

Parameters:

  • dry_run (bool) – Whether to compute the result without mutating storage

  • prune_cache (bool) – Whether rebuildable cache areas should be pruned

Returns:

GC report

Return type:

hubvault.models.GcReport

get_commit_detail(commit_id: str, *, formatted: bool = False)[source]

Return one remote commit together with its first-parent file changes.

Parameters:

  • commit_id (str) – Public commit ID or revision resolving to a commit

  • formatted (bool) – Whether HTML-formatted title/message fields should be populated

Returns:

Commit metadata with file-level changes

Return type:

hubvault.models.CommitDetailInfo

get_paths_info(paths: Sequence[str] | str, *, revision: str | None = None)[source]

Return public metadata for selected remote paths.

Parameters:

  • paths (Union[Sequence[str], str]) – Repo-relative path or paths to inspect

  • revision (Optional[str]) – Revision to resolve, defaults to the client default revision

Returns:

Metadata for the existing requested paths

Return type:

List[Union[hubvault.models.RepoFile, hubvault.models.RepoFolder]]

Raises:
get_storage_overview()[source]

Fetch the remote storage-overview report.

Returns:

Storage overview

Return type:

hubvault.models.StorageOverview

hf_hub_download(filename: str, *, revision: str | None = None, local_dir: str | PathLike | None = None) → str[source]

Materialize a detached local path for one remote file.

Parameters:

  • filename (str) – Repo-relative file path

  • revision (Optional[str]) – Revision to resolve, defaults to the client default revision

  • local_dir (Optional[Union[str, os.PathLike]]) – Optional export directory outside the client cache

Returns:

A filesystem path that can be read safely

Return type:

str

Raises:
list_repo_commits(*, revision: str | None = None, formatted: bool = False)[source]

List commits reachable from a remote revision in HF-style order.

Parameters:

  • revision (Optional[str]) – Revision to resolve, defaults to the client default revision

  • formatted (bool) – Whether HTML-formatted title/message fields should be populated

Returns:

Commit entries ordered from newest to oldest

Return type:

Sequence[hubvault.models.GitCommitInfo]

Raises:
list_repo_files(*, revision: str | None = None) → Sequence[str][source]

List all remote file paths in a revision.

Parameters:

revision (Optional[str]) – Revision to resolve, defaults to the client default revision

Returns:

Sorted repo-relative file paths

Return type:

Sequence[str]

Raises:
list_repo_reflog(ref_name: str, *, limit: int | None = None)[source]

List reflog entries for a remote branch or tag.

Parameters:

  • ref_name (str) – Full ref name or an unambiguous short ref name

  • limit (Optional[int]) – Optional maximum number of newest entries to return

Returns:

Reflog entries ordered from newest to oldest

Return type:

Sequence[hubvault.models.ReflogEntry]

Raises:
list_repo_refs(*, include_pull_requests: bool = False)[source]

List visible remote branch and tag refs in HF-style form.

Parameters:

include_pull_requests (bool) – Whether pull-request refs should be included

Returns:

Visible repository refs

Return type:

hubvault.models.GitRefs

Raises:
list_repo_tree(path_in_repo: str | None = None, *, recursive: bool = False, revision: str | None = None)[source]

List direct children under a remote repository directory.

Parameters:

  • path_in_repo (Optional[str]) – Repo-relative directory path, defaults to the root

  • recursive (bool) – Whether to include descendant entries recursively

  • revision (Optional[str]) – Revision to resolve, defaults to the client default revision

Returns:

Direct child path metadata

Return type:

List[Union[hubvault.models.RepoFile, hubvault.models.RepoFolder]]

Raises:
merge(source_revision: str, *, target_revision: str | None = None, parent_commit: str | None = None, commit_message: str | None = None, commit_description: str | None = None)[source]

Merge one remote source revision into a target branch.

Parameters:

  • source_revision (str) – Source revision to merge

  • target_revision (Optional[str]) – Optional target branch override

  • parent_commit (Optional[str]) – Optional optimistic-concurrency base head

  • commit_message (Optional[str]) – Optional merge-commit title

  • commit_description (Optional[str]) – Optional merge-commit body

Returns:

Structured merge result

Return type:

hubvault.models.MergeResult

open_file(path_in_repo: str, *, revision: str | None = None) → BinaryIO[source]

Open a remote file as a read-only binary stream.

Parameters:

  • path_in_repo (str) – Repo-relative file path

  • revision (Optional[str]) – Revision to resolve, defaults to the client default revision

Returns:

Read-only binary stream backed by a detached local file

Return type:

BinaryIO

Raises:
quick_verify()[source]

Run the remote quick verification pass.

Returns:

Verification report

Return type:

hubvault.models.VerifyReport

read_bytes(path_in_repo: str, *, revision: str | None = None) → bytes[source]

Read the full remote content of a file.

Parameters:

  • path_in_repo (str) – Repo-relative file path

  • revision (Optional[str]) – Revision to resolve, defaults to the client default revision

Returns:

File content bytes

Return type:

bytes

Raises:
read_range(path_in_repo: str, *, start: int, length: int, revision: str | None = None) → bytes[source]

Read a byte range from a remote file.

Parameters:

  • path_in_repo (str) – Repo-relative file path

  • start (int) – Starting byte offset in the logical file

  • length (int) – Number of bytes to read

  • revision (Optional[str]) – Revision to resolve, defaults to the client default revision

Returns:

Requested byte range, clamped to the file end

Return type:

bytes

Raises:
repo_info(*, revision: str | None = None)[source]

Return metadata about the remote repository.

Parameters:

revision (Optional[str]) – Revision to resolve, defaults to the client default revision

Returns:

Repository metadata

Return type:

hubvault.models.RepoInfo

Raises:
reset_ref(ref_name: str, *, to_revision: str)[source]

Reset one remote branch ref to a target revision.

Parameters:

  • ref_name (str) – Branch name to update

  • to_revision (str) – Revision to resolve as the new head

Returns:

Commit metadata for the new head

Return type:

hubvault.models.CommitInfo

snapshot_download(*, revision: str | None = None, local_dir: str | PathLike | None = None, allow_patterns: Sequence[str] | str | None = None, ignore_patterns: Sequence[str] | str | None = None) → str[source]

Materialize a detached local snapshot directory for a remote revision.

Parameters:

  • revision (Optional[str]) – Revision to resolve, defaults to the client default revision

  • local_dir (Optional[Union[str, os.PathLike]]) – Optional export directory outside the client cache

  • allow_patterns (Optional[Union[Sequence[str], str]]) – Optional allowlist for repo-relative paths

  • ignore_patterns (Optional[Union[Sequence[str], str]]) – Optional denylist for repo-relative paths

Returns:

Filesystem path to the detached snapshot directory

Return type:

str

Raises:
squash_history(ref_name: str, *, root_revision: str | None = None, commit_message: str | None = None, commit_description: str | None = None, run_gc: bool = True, prune_cache: bool = False)[source]

Rewrite one remote branch history chain.

Parameters:

  • ref_name (str) – Branch name or full branch ref to rewrite

  • root_revision (Optional[str]) – Optional oldest commit to preserve

  • commit_message (Optional[str]) – Optional replacement root title

  • commit_description (Optional[str]) – Optional replacement root body

  • run_gc (bool) – Whether a GC pass should run immediately after rewriting

  • prune_cache (bool) – Whether the follow-up GC should also prune caches

Returns:

History-squash report

Return type:

hubvault.models.SquashReport

upload_file(*, path_or_fileobj: str | PathLike | bytes | BinaryIO, path_in_repo: str, revision: str | None = None, commit_message: str | None = None, commit_description: str | None = None, parent_commit: str | None = None, progress_callback: Callable[[int, int], None] | None = None, show_progress: bool = False)[source]

Upload one file through the remote planned-commit protocol.

Parameters:

  • path_or_fileobj (Union[str, os.PathLike[str], bytes, BinaryIO]) – File content source

  • path_in_repo (str) – Target repo-relative path

  • revision (Optional[str]) – Optional target branch override

  • commit_message (Optional[str]) – Optional commit summary

  • commit_description (Optional[str]) – Optional commit description/body

  • parent_commit (Optional[str]) – Optional optimistic-concurrency base head

  • progress_callback (Optional[Callable[[int, int], None]]) – Optional callback receiving (sent, total) upload-byte updates for streamed file/chunk parts

  • show_progress (bool) – Whether to show a tqdm progress bar when no explicit callback is provided

Returns:

Commit metadata for the created commit

Return type:

hubvault.models.CommitInfo

upload_folder(*, folder_path: str | PathLike, path_in_repo: str | None = None, commit_message: str | None = None, commit_description: str | None = None, revision: str | None = None, parent_commit: str | None = None, allow_patterns: Sequence[str] | str | None = None, ignore_patterns: Sequence[str] | str | None = None, delete_patterns: Sequence[str] | str | None = None, progress_callback: Callable[[int, int], None] | None = None, show_progress: bool = False)[source]

Upload one local folder through the remote planned-commit protocol.

Parameters:

  • folder_path (Union[str, os.PathLike[str]]) – Local folder to upload

  • path_in_repo (Optional[str]) – Optional target directory in the repo

  • commit_message (Optional[str]) – Optional commit summary

  • commit_description (Optional[str]) – Optional commit description/body

  • revision (Optional[str]) – Optional target branch override

  • parent_commit (Optional[str]) – Optional optimistic-concurrency base head

  • allow_patterns (Optional[Union[Sequence[str], str]]) – Optional allowlist for local relative paths

  • ignore_patterns (Optional[Union[Sequence[str], str]]) – Optional denylist for local relative paths

  • delete_patterns (Optional[Union[Sequence[str], str]]) – Optional denylist applied to already uploaded repo files below path_in_repo

  • progress_callback (Optional[Callable[[int, int], None]]) – Optional callback receiving (sent, total) upload-byte updates for streamed file/chunk parts

  • show_progress (bool) – Whether to show a tqdm progress bar when no explicit callback is provided

Returns:

Commit metadata for the created commit

Return type:

hubvault.models.CommitInfo

Raises:

ValueError – Raised when folder_path is not a local directory.

upload_large_folder(*, folder_path: str | PathLike, revision: str | None = None, allow_patterns: Sequence[str] | str | None = None, ignore_patterns: Sequence[str] | str | None = None, progress_callback: Callable[[int, int], None] | None = None, show_progress: bool = False)[source]

Upload one local folder through the remote large-folder flow.

Parameters:

  • folder_path (Union[str, os.PathLike[str]]) – Local folder to upload

  • revision (Optional[str]) – Optional target branch override

  • allow_patterns (Optional[Union[Sequence[str], str]]) – Optional allowlist for local relative paths

  • ignore_patterns (Optional[Union[Sequence[str], str]]) – Optional denylist for local relative paths

  • progress_callback (Optional[Callable[[int, int], None]]) – Optional callback receiving (sent, total) upload-byte updates for streamed file/chunk parts

  • show_progress (bool) – Whether to show a tqdm progress bar when no explicit callback is provided

Returns:

Commit metadata for the created commit

Return type:

hubvault.models.CommitInfo