huggingface-hub 0.31.0rc0__py3-none-any.whl → 1.1.3__py3-none-any.whl

huggingface_hub/cli/download.py

@@ -0,0 +1,189 @@
+# coding=utf-8
+# Copyright 202-present, the HuggingFace Inc. team.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Contains command to download files from the Hub with the CLI.
+
+Usage:
+    hf download --help
+
+    # Download file
+    hf download gpt2 config.json
+
+    # Download entire repo
+    hf download fffiloni/zeroscope --repo-type=space --revision=refs/pr/78
+
+    # Download repo with filters
+    hf download gpt2 --include="*.safetensors"
+
+    # Download with token
+    hf download Wauplin/private-model --token=hf_***
+
+    # Download quietly (no progress bar, no warnings, only the returned path)
+    hf download gpt2 config.json --quiet
+
+    # Download to local dir
+    hf download gpt2 --local-dir=./models/gpt2
+"""
+
+import warnings
+from typing import Annotated, Optional, Union
+
+import typer
+
+from huggingface_hub import logging
+from huggingface_hub._snapshot_download import snapshot_download
+from huggingface_hub.file_download import DryRunFileInfo, hf_hub_download
+from huggingface_hub.utils import _format_size, disable_progress_bars, enable_progress_bars, tabulate
+
+from ._cli_utils import RepoIdArg, RepoTypeOpt, RevisionOpt, TokenOpt
+
+
+logger = logging.get_logger(__name__)
+
+
+def download(
+    repo_id: RepoIdArg,
+    filenames: Annotated[
+        Optional[list[str]],
+        typer.Argument(
+            help="Files to download (e.g. `config.json`, `data/metadata.jsonl`).",
+        ),
+    ] = None,
+    repo_type: RepoTypeOpt = RepoTypeOpt.model,
+    revision: RevisionOpt = None,
+    include: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to include from files to download. eg: *.json",
+        ),
+    ] = None,
+    exclude: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to exclude from files to download.",
+        ),
+    ] = None,
+    cache_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Directory where to save files.",
+        ),
+    ] = None,
+    local_dir: Annotated[
+        Optional[str],
+        typer.Option(
+            help="If set, the downloaded file will be placed under this directory. Check out https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-local-folder for more details.",
+        ),
+    ] = None,
+    force_download: Annotated[
+        bool,
+        typer.Option(
+            help="If True, the files will be downloaded even if they are already cached.",
+        ),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            help="If True, perform a dry run without actually downloading the file.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            help="If True, progress bars are disabled and only the path to the download files is printed.",
+        ),
+    ] = False,
+    max_workers: Annotated[
+        int,
+        typer.Option(
+            help="Maximum number of workers to use for downloading files. Default is 8.",
+        ),
+    ] = 8,
+) -> None:
+    """Download files from the Hub."""
+
+    def run_download() -> Union[str, DryRunFileInfo, list[DryRunFileInfo]]:
+        filenames_list = filenames if filenames is not None else []
+        # Warn user if patterns are ignored
+        if len(filenames_list) > 0:
+            if include is not None and len(include) > 0:
+                warnings.warn("Ignoring `--include` since filenames have being explicitly set.")
+            if exclude is not None and len(exclude) > 0:
+                warnings.warn("Ignoring `--exclude` since filenames have being explicitly set.")
+
+        # Single file to download: use `hf_hub_download`
+        if len(filenames_list) == 1:
+            return hf_hub_download(
+                repo_id=repo_id,
+                repo_type=repo_type.value,
+                revision=revision,
+                filename=filenames_list[0],
+                cache_dir=cache_dir,
+                force_download=force_download,
+                token=token,
+                local_dir=local_dir,
+                library_name="huggingface-cli",
+                dry_run=dry_run,
+            )
+
+        # Otherwise: use `snapshot_download` to ensure all files comes from same revision
+        if len(filenames_list) == 0:
+            allow_patterns = include
+            ignore_patterns = exclude
+        else:
+            allow_patterns = filenames_list
+            ignore_patterns = None
+
+        return snapshot_download(
+            repo_id=repo_id,
+            repo_type=repo_type.value,
+            revision=revision,
+            allow_patterns=allow_patterns,
+            ignore_patterns=ignore_patterns,
+            force_download=force_download,
+            cache_dir=cache_dir,
+            token=token,
+            local_dir=local_dir,
+            library_name="huggingface-cli",
+            max_workers=max_workers,
+            dry_run=dry_run,
+        )
+
+    def _print_result(result: Union[str, DryRunFileInfo, list[DryRunFileInfo]]) -> None:
+        if isinstance(result, str):
+            print(result)
+            return
+
+        # Print dry run info
+        if isinstance(result, DryRunFileInfo):
+            result = [result]
+        print(
+            f"[dry-run] Will download {len([r for r in result if r.will_download])} files (out of {len(result)}) totalling {_format_size(sum(r.file_size for r in result if r.will_download))}."
+        )
+        columns = ["File", "Bytes to download"]
+        items: list[list[Union[str, int]]] = []
+        for info in sorted(result, key=lambda x: x.filename):
+            items.append([info.filename, _format_size(info.file_size) if info.will_download else "-"])
+        print(tabulate(items, headers=columns))
+
+    if quiet:
+        disable_progress_bars()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            _print_result(run_download())
+        enable_progress_bars()
+    else:
+        _print_result(run_download())
+        logging.set_verbosity_warning()

huggingface_hub/cli/hf.py

@@ -0,0 +1,60 @@
+# Copyright 2020 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from huggingface_hub.cli._cli_utils import check_cli_update, typer_factory
+from huggingface_hub.cli.auth import auth_cli
+from huggingface_hub.cli.cache import cache_cli
+from huggingface_hub.cli.download import download
+from huggingface_hub.cli.inference_endpoints import ie_cli
+from huggingface_hub.cli.jobs import jobs_cli
+from huggingface_hub.cli.lfs import lfs_enable_largefiles, lfs_multipart_upload
+from huggingface_hub.cli.repo import repo_cli
+from huggingface_hub.cli.repo_files import repo_files_cli
+from huggingface_hub.cli.system import env, version
+from huggingface_hub.cli.upload import upload
+from huggingface_hub.cli.upload_large_folder import upload_large_folder
+from huggingface_hub.utils import logging
+
+
+app = typer_factory(help="Hugging Face Hub CLI")
+
+
+# top level single commands (defined in their respective files)
+app.command(help="Download files from the Hub.")(download)
+app.command(help="Upload a file or a folder to the Hub.")(upload)
+app.command(help="Upload a large folder to the Hub. Recommended for resumable uploads.")(upload_large_folder)
+app.command(name="env", help="Print information about the environment.")(env)
+app.command(help="Print information about the hf version.")(version)
+app.command(help="Configure your repository to enable upload of files > 5GB.", hidden=True)(lfs_enable_largefiles)
+app.command(help="Upload large files to the Hub.", hidden=True)(lfs_multipart_upload)
+
+
+# command groups
+app.add_typer(auth_cli, name="auth")
+app.add_typer(cache_cli, name="cache")
+app.add_typer(repo_cli, name="repo")
+app.add_typer(repo_files_cli, name="repo-files")
+app.add_typer(jobs_cli, name="jobs")
+app.add_typer(ie_cli, name="endpoints")
+
+
+def main():
+    logging.set_verbosity_info()
+    check_cli_update()
+    app()
+
+
+if __name__ == "__main__":
+    main()

huggingface_hub/cli/inference_endpoints.py

@@ -0,0 +1,377 @@
+"""CLI commands for Hugging Face Inference Endpoints."""
+
+import json
+from typing import Annotated, Optional
+
+import typer
+
+from huggingface_hub._inference_endpoints import InferenceEndpoint
+from huggingface_hub.errors import HfHubHTTPError
+
+from ._cli_utils import TokenOpt, get_hf_api, typer_factory
+
+
+ie_cli = typer_factory(help="Manage Hugging Face Inference Endpoints.")
+
+catalog_app = typer_factory(help="Interact with the Inference Endpoints catalog.")
+
+NameArg = Annotated[
+    str,
+    typer.Argument(help="Endpoint name."),
+]
+NameOpt = Annotated[
+    Optional[str],
+    typer.Option(help="Endpoint name."),
+]
+
+NamespaceOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="The namespace associated with the Inference Endpoint. Defaults to the current user's namespace.",
+    ),
+]
+
+
+def _print_endpoint(endpoint: InferenceEndpoint) -> None:
+    typer.echo(json.dumps(endpoint.raw, indent=2, sort_keys=True))
+
+
+@ie_cli.command()
+def ls(
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Lists all Inference Endpoints for the given namespace."""
+    api = get_hf_api(token=token)
+    try:
+        endpoints = api.list_inference_endpoints(namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Listing failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    typer.echo(
+        json.dumps(
+            {"items": [endpoint.raw for endpoint in endpoints]},
+            indent=2,
+            sort_keys=True,
+        )
+    )
+
+
+@ie_cli.command(name="deploy")
+def deploy(
+    name: NameArg,
+    repo: Annotated[
+        str,
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ],
+    framework: Annotated[
+        str,
+        typer.Option(
+            help="The machine learning framework used for the model (e.g. 'vllm').",
+        ),
+    ],
+    accelerator: Annotated[
+        str,
+        typer.Option(
+            help="The hardware accelerator to be used for inference (e.g. 'cpu').",
+        ),
+    ],
+    instance_size: Annotated[
+        str,
+        typer.Option(
+            help="The size or type of the instance to be used for hosting the model (e.g. 'x4').",
+        ),
+    ],
+    instance_type: Annotated[
+        str,
+        typer.Option(
+            help="The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl').",
+        ),
+    ],
+    region: Annotated[
+        str,
+        typer.Option(
+            help="The cloud region in which the Inference Endpoint will be created (e.g. 'us-east-1').",
+        ),
+    ],
+    vendor: Annotated[
+        str,
+        typer.Option(
+            help="The cloud provider or vendor where the Inference Endpoint will be hosted (e.g. 'aws').",
+        ),
+    ],
+    *,
+    namespace: NamespaceOpt = None,
+    task: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The task on which to deploy the model (e.g. 'text-classification').",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    """Deploy an Inference Endpoint from a Hub repository."""
+    api = get_hf_api(token=token)
+    endpoint = api.create_inference_endpoint(
+        name=name,
+        repository=repo,
+        framework=framework,
+        accelerator=accelerator,
+        instance_size=instance_size,
+        instance_type=instance_type,
+        region=region,
+        vendor=vendor,
+        namespace=namespace,
+        task=task,
+        token=token,
+    )
+
+    _print_endpoint(endpoint)
+
+
+@catalog_app.command(name="deploy")
+def deploy_from_catalog(
+    repo: Annotated[
+        str,
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ],
+    name: NameOpt = None,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Deploy an Inference Endpoint from the Model Catalog."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.create_inference_endpoint_from_catalog(
+            repo_id=repo,
+            name=name,
+            namespace=namespace,
+            token=token,
+        )
+    except HfHubHTTPError as error:
+        typer.echo(f"Deployment failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    _print_endpoint(endpoint)
+
+
+def list_catalog(
+    token: TokenOpt = None,
+) -> None:
+    """List available Catalog models."""
+    api = get_hf_api(token=token)
+    try:
+        models = api.list_inference_catalog(token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Catalog fetch failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    typer.echo(json.dumps({"models": models}, indent=2, sort_keys=True))
+
+
+catalog_app.command(name="ls")(list_catalog)
+ie_cli.command(name="list-catalog", help="List available Catalog models.", hidden=True)(list_catalog)
+
+
+ie_cli.add_typer(catalog_app, name="catalog")
+
+
+@ie_cli.command()
+def describe(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Get information about an existing endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.get_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Fetch failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    _print_endpoint(endpoint)
+
+
+@ie_cli.command()
+def update(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    repo: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').",
+        ),
+    ] = None,
+    accelerator: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The hardware accelerator to be used for inference (e.g. 'cpu').",
+        ),
+    ] = None,
+    instance_size: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The size or type of the instance to be used for hosting the model (e.g. 'x4').",
+        ),
+    ] = None,
+    instance_type: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl').",
+        ),
+    ] = None,
+    framework: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The machine learning framework used for the model (e.g. 'custom').",
+        ),
+    ] = None,
+    revision: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The specific model revision to deploy on the Inference Endpoint (e.g. '6c0e6080953db56375760c0471a8c5f2929baf11').",
+        ),
+    ] = None,
+    task: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The task on which to deploy the model (e.g. 'text-classification').",
+        ),
+    ] = None,
+    min_replica: Annotated[
+        Optional[int],
+        typer.Option(
+            help="The minimum number of replicas (instances) to keep running for the Inference Endpoint.",
+        ),
+    ] = None,
+    max_replica: Annotated[
+        Optional[int],
+        typer.Option(
+            help="The maximum number of replicas (instances) to scale to for the Inference Endpoint.",
+        ),
+    ] = None,
+    scale_to_zero_timeout: Annotated[
+        Optional[int],
+        typer.Option(
+            help="The duration in minutes before an inactive endpoint is scaled to zero.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    """Update an existing endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.update_inference_endpoint(
+            name=name,
+            namespace=namespace,
+            repository=repo,
+            framework=framework,
+            revision=revision,
+            task=task,
+            accelerator=accelerator,
+            instance_size=instance_size,
+            instance_type=instance_type,
+            min_replica=min_replica,
+            max_replica=max_replica,
+            scale_to_zero_timeout=scale_to_zero_timeout,
+            token=token,
+        )
+    except HfHubHTTPError as error:
+        typer.echo(f"Update failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+    _print_endpoint(endpoint)
+
+
+@ie_cli.command()
+def delete(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", help="Skip confirmation prompts."),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Delete an Inference Endpoint permanently."""
+    if not yes:
+        confirmation = typer.prompt(f"Delete endpoint '{name}'? Type the name to confirm.")
+        if confirmation != name:
+            typer.echo("Aborted.")
+            raise typer.Exit(code=2)
+
+    api = get_hf_api(token=token)
+    try:
+        api.delete_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Delete failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    typer.echo(f"Deleted '{name}'.")
+
+
+@ie_cli.command()
+def pause(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Pause an Inference Endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.pause_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Pause failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    _print_endpoint(endpoint)
+
+
+@ie_cli.command()
+def resume(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    fail_if_already_running: Annotated[
+        bool,
+        typer.Option(
+            "--fail-if-already-running",
+            help="If `True`, the method will raise an error if the Inference Endpoint is already running.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    """Resume an Inference Endpoint."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.resume_inference_endpoint(
+            name=name,
+            namespace=namespace,
+            token=token,
+            running_ok=not fail_if_already_running,
+        )
+    except HfHubHTTPError as error:
+        typer.echo(f"Resume failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+    _print_endpoint(endpoint)
+
+
+@ie_cli.command()
+def scale_to_zero(
+    name: NameArg,
+    namespace: NamespaceOpt = None,
+    token: TokenOpt = None,
+) -> None:
+    """Scale an Inference Endpoint to zero."""
+    api = get_hf_api(token=token)
+    try:
+        endpoint = api.scale_to_zero_inference_endpoint(name=name, namespace=namespace, token=token)
+    except HfHubHTTPError as error:
+        typer.echo(f"Scale To Zero failed: {error}")
+        raise typer.Exit(code=error.response.status_code) from error
+
+    _print_endpoint(endpoint)