huggingface-hub 0.36.0rc0__py3-none-any.whl → 1.0.0__py3-none-any.whl

huggingface_hub/cli/repo_files.py

@@ -34,95 +34,61 @@ Usage:
     hf repo-files delete <repo_id> file.txt --revision=refs/pr/1 --repo-type=dataset
 """
 
-from argparse import _SubParsersAction
-from typing import List, Optional
+from typing import Annotated, Optional
+
+import typer
 
 from huggingface_hub import logging
-from huggingface_hub.commands import BaseHuggingfaceCLICommand
-from huggingface_hub.hf_api import HfApi
+
+from ._cli_utils import RepoIdArg, RepoType, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api, typer_factory
 
 
 logger = logging.get_logger(__name__)
 
 
-class DeleteFilesSubCommand:
-    def __init__(self, args) -> None:
-        self.args = args
-        self.repo_id: str = args.repo_id
-        self.repo_type: Optional[str] = args.repo_type
-        self.revision: Optional[str] = args.revision
-        self.api: HfApi = HfApi(token=args.token, library_name="huggingface-cli")
-        self.patterns: List[str] = args.patterns
-        self.commit_message: Optional[str] = args.commit_message
-        self.commit_description: Optional[str] = args.commit_description
-        self.create_pr: bool = args.create_pr
-        self.token: Optional[str] = args.token
-
-    def run(self) -> None:
-        logging.set_verbosity_info()
-        url = self.api.delete_files(
-            delete_patterns=self.patterns,
-            repo_id=self.repo_id,
-            repo_type=self.repo_type,
-            revision=self.revision,
-            commit_message=self.commit_message,
-            commit_description=self.commit_description,
-            create_pr=self.create_pr,
-        )
-        print(f"Files correctly deleted from repo. Commit: {url}.")
-        logging.set_verbosity_warning()
-
-
-class RepoFilesCommand(BaseHuggingfaceCLICommand):
-    @staticmethod
-    def register_subcommand(parser: _SubParsersAction):
-        repo_files_parser = parser.add_parser("repo-files", help="Manage files in a repo on the Hub.")
-        repo_files_subparsers = repo_files_parser.add_subparsers(
-            help="Action to execute against the files.",
-            required=True,
-        )
-        delete_subparser = repo_files_subparsers.add_parser(
-            "delete",
-            help="Delete files from a repo on the Hub",
-        )
-        delete_subparser.set_defaults(func=lambda args: DeleteFilesSubCommand(args))
-        delete_subparser.add_argument(
-            "repo_id", type=str, help="The ID of the repo to manage (e.g. `username/repo-name`)."
-        )
-        delete_subparser.add_argument(
-            "patterns",
-            nargs="+",
-            type=str,
+repo_files_cli = typer_factory(help="Manage files in a repo on the Hub.")
+
+
+@repo_files_cli.command("delete")
+def repo_files_delete(
+    repo_id: RepoIdArg,
+    patterns: Annotated[
+        list[str],
+        typer.Argument(
             help="Glob patterns to match files to delete.",
-        )
-        delete_subparser.add_argument(
-            "--repo-type",
-            choices=["model", "dataset", "space"],
-            default="model",
-            help="Type of the repo to upload to (e.g. `dataset`).",
-        )
-        delete_subparser.add_argument(
-            "--revision",
-            type=str,
-            help=(
-                "An optional Git revision to push to. It can be a branch name "
-                "or a PR reference. If revision does not"
-                " exist and `--create-pr` is not set, a branch will be automatically created."
-            ),
-        )
-        delete_subparser.add_argument(
-            "--commit-message", type=str, help="The summary / title / first line of the generated commit."
-        )
-        delete_subparser.add_argument(
-            "--commit-description", type=str, help="The description of the generated commit."
-        )
-        delete_subparser.add_argument(
-            "--create-pr", action="store_true", help="Whether to create a new Pull Request for these changes."
-        )
-        delete_subparser.add_argument(
-            "--token",
-            type=str,
-            help="A User Access Token generated from https://huggingface.co/settings/tokens",
-        )
-
-        repo_files_parser.set_defaults(func=RepoFilesCommand)
+        ),
+    ],
+    repo_type: RepoTypeOpt = RepoType.model,
+    revision: RevisionOpt = None,
+    commit_message: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The summary / title / first line of the generated commit.",
+        ),
+    ] = None,
+    commit_description: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The description of the generated commit.",
+        ),
+    ] = None,
+    create_pr: Annotated[
+        bool,
+        typer.Option(
+            help="Whether to create a new Pull Request for these changes.",
+        ),
+    ] = False,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+    url = api.delete_files(
+        delete_patterns=patterns,
+        repo_id=repo_id,
+        repo_type=repo_type.value,
+        revision=revision,
+        commit_message=commit_message,
+        commit_description=commit_description,
+        create_pr=create_pr,
+    )
+    print(f"Files correctly deleted from repo. Commit: {url}.")
+    logging.set_verbosity_warning()

huggingface_hub/cli/system.py

@@ -18,35 +18,16 @@ Usage:
     hf version
 """
 
-from argparse import _SubParsersAction
-
 from huggingface_hub import __version__
 
 from ..utils import dump_environment_info
-from . import BaseHuggingfaceCLICommand
-
-
-class EnvironmentCommand(BaseHuggingfaceCLICommand):
-    def __init__(self, args):
-        self.args = args
-
-    @staticmethod
-    def register_subcommand(parser: _SubParsersAction):
-        env_parser = parser.add_parser("env", help="Print information about the environment.")
-        env_parser.set_defaults(func=EnvironmentCommand)
-
-    def run(self) -> None:
-        dump_environment_info()
 
 
-class VersionCommand(BaseHuggingfaceCLICommand):
-    def __init__(self, args):
-        self.args = args
+def env() -> None:
+    """Print information about the environment."""
+    dump_environment_info()
 
-    @staticmethod
-    def register_subcommand(parser: _SubParsersAction):
-        version_parser = parser.add_parser("version", help="Print information about the hf version.")
-        version_parser.set_defaults(func=VersionCommand)
 
-    def run(self) -> None:
-        print(f"huggingface_hub version: {__version__}")
+def version() -> None:
+    """Print CLI version."""
+    print(__version__)

huggingface_hub/cli/upload.py

@@ -49,215 +49,151 @@ Usage:
 import os
 import time
 import warnings
-from argparse import Namespace, _SubParsersAction
-from typing import List, Optional
+from typing import Annotated, Optional
+
+import typer
 
 from huggingface_hub import logging
 from huggingface_hub._commit_scheduler import CommitScheduler
-from huggingface_hub.commands import BaseHuggingfaceCLICommand
-from huggingface_hub.constants import HF_HUB_ENABLE_HF_TRANSFER
 from huggingface_hub.errors import RevisionNotFoundError
-from huggingface_hub.hf_api import HfApi
 from huggingface_hub.utils import disable_progress_bars, enable_progress_bars
-from huggingface_hub.utils._runtime import is_xet_available
+
+from ._cli_utils import PrivateOpt, RepoIdArg, RepoType, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api
 
 
 logger = logging.get_logger(__name__)
 
 
-class UploadCommand(BaseHuggingfaceCLICommand):
-    @staticmethod
-    def register_subcommand(parser: _SubParsersAction):
-        upload_parser = parser.add_parser(
-            "upload", help="Upload a file or a folder to the Hub. Recommended for single-commit uploads."
-        )
-        upload_parser.add_argument(
-            "repo_id", type=str, help="The ID of the repo to upload to (e.g. `username/repo-name`)."
-        )
-        upload_parser.add_argument(
-            "local_path",
-            nargs="?",
+def upload(
+    repo_id: RepoIdArg,
+    local_path: Annotated[
+        Optional[str],
+        typer.Argument(
             help="Local path to the file or folder to upload. Wildcard patterns are supported. Defaults to current directory.",
-        )
-        upload_parser.add_argument(
-            "path_in_repo",
-            nargs="?",
+        ),
+    ] = None,
+    path_in_repo: Annotated[
+        Optional[str],
+        typer.Argument(
             help="Path of the file or folder in the repo. Defaults to the relative path of the file or folder.",
-        )
-        upload_parser.add_argument(
-            "--repo-type",
-            choices=["model", "dataset", "space"],
-            default="model",
-            help="Type of the repo to upload to (e.g. `dataset`).",
-        )
-        upload_parser.add_argument(
-            "--revision",
-            type=str,
-            help=(
-                "An optional Git revision to push to. It can be a branch name or a PR reference. If revision does not"
-                " exist and `--create-pr` is not set, a branch will be automatically created."
-            ),
-        )
-        upload_parser.add_argument(
-            "--private",
-            action="store_true",
-            help=(
-                "Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already"
-                " exists."
-            ),
-        )
-        upload_parser.add_argument("--include", nargs="*", type=str, help="Glob patterns to match files to upload.")
-        upload_parser.add_argument(
-            "--exclude", nargs="*", type=str, help="Glob patterns to exclude from files to upload."
-        )
-        upload_parser.add_argument(
-            "--delete",
-            nargs="*",
-            type=str,
+        ),
+    ] = None,
+    repo_type: RepoTypeOpt = RepoType.model,
+    revision: RevisionOpt = None,
+    private: PrivateOpt = False,
+    include: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to match files to upload.",
+        ),
+    ] = None,
+    exclude: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            help="Glob patterns to exclude from files to upload.",
+        ),
+    ] = None,
+    delete: Annotated[
+        Optional[list[str]],
+        typer.Option(
             help="Glob patterns for file to be deleted from the repo while committing.",
-        )
-        upload_parser.add_argument(
-            "--commit-message", type=str, help="The summary / title / first line of the generated commit."
-        )
-        upload_parser.add_argument("--commit-description", type=str, help="The description of the generated commit.")
-        upload_parser.add_argument(
-            "--create-pr", action="store_true", help="Whether to upload content as a new Pull Request."
-        )
-        upload_parser.add_argument(
-            "--every",
-            type=float,
-            help="If set, a background job is scheduled to create commits every `every` minutes.",
-        )
-        upload_parser.add_argument(
-            "--token", type=str, help="A User Access Token generated from https://huggingface.co/settings/tokens"
-        )
-        upload_parser.add_argument(
-            "--quiet",
-            action="store_true",
-            help="If True, progress bars are disabled and only the path to the uploaded files is printed.",
-        )
-        upload_parser.set_defaults(func=UploadCommand)
-
-    def __init__(self, args: Namespace) -> None:
-        self.repo_id: str = args.repo_id
-        self.repo_type: Optional[str] = args.repo_type
-        self.revision: Optional[str] = args.revision
-        self.private: bool = args.private
-
-        self.include: Optional[List[str]] = args.include
-        self.exclude: Optional[List[str]] = args.exclude
-        self.delete: Optional[List[str]] = args.delete
-
-        self.commit_message: Optional[str] = args.commit_message
-        self.commit_description: Optional[str] = args.commit_description
-        self.create_pr: bool = args.create_pr
-        self.api: HfApi = HfApi(token=args.token, library_name="huggingface-cli")
-        self.quiet: bool = args.quiet  # disable warnings and progress bars
-
-        # Check `--every` is valid
-        if args.every is not None and args.every <= 0:
-            raise ValueError(f"`every` must be a positive value (got '{args.every}')")
-        self.every: Optional[float] = args.every
-
-        # Resolve `local_path` and `path_in_repo`
-        repo_name: str = args.repo_id.split("/")[-1]  # e.g. "Wauplin/my-cool-model" => "my-cool-model"
-        self.local_path: str
-        self.path_in_repo: str
-
-        if args.local_path is not None and any(c in args.local_path for c in ["*", "?", "["]):
-            if args.include is not None:
-                raise ValueError("Cannot set `--include` when passing a `local_path` containing a wildcard.")
-            if args.path_in_repo is not None and args.path_in_repo != ".":
-                raise ValueError("Cannot set `path_in_repo` when passing a `local_path` containing a wildcard.")
-            self.local_path = "."
-            self.include = args.local_path
-            self.path_in_repo = "."
-        elif args.local_path is None and os.path.isfile(repo_name):
-            # Implicit case 1: user provided only a repo_id which happen to be a local file as well => upload it with same name
-            self.local_path = repo_name
-            self.path_in_repo = repo_name
-        elif args.local_path is None and os.path.isdir(repo_name):
-            # Implicit case 2: user provided only a repo_id which happen to be a local folder as well => upload it at root
-            self.local_path = repo_name
-            self.path_in_repo = "."
-        elif args.local_path is None:
-            # Implicit case 3: user provided only a repo_id that does not match a local file or folder
-            # => the user must explicitly provide a local_path => raise exception
-            raise ValueError(f"'{repo_name}' is not a local file or folder. Please set `local_path` explicitly.")
-        elif args.path_in_repo is None and os.path.isfile(args.local_path):
-            # Explicit local path to file, no path in repo => upload it at root with same name
-            self.local_path = args.local_path
-            self.path_in_repo = os.path.basename(args.local_path)
-        elif args.path_in_repo is None:
-            # Explicit local path to folder, no path in repo => upload at root
-            self.local_path = args.local_path
-            self.path_in_repo = "."
-        else:
-            # Finally, if both paths are explicit
-            self.local_path = args.local_path
-            self.path_in_repo = args.path_in_repo
-
-    def run(self) -> None:
-        if self.quiet:
-            disable_progress_bars()
-            with warnings.catch_warnings():
-                warnings.simplefilter("ignore")
-                print(self._upload())
-            enable_progress_bars()
-        else:
-            logging.set_verbosity_info()
-            print(self._upload())
-            logging.set_verbosity_warning()
-
-    def _upload(self) -> str:
-        if os.path.isfile(self.local_path):
-            if self.include is not None and len(self.include) > 0:
-                warnings.warn("Ignoring `--include` since a single file is uploaded.")
-            if self.exclude is not None and len(self.exclude) > 0:
-                warnings.warn("Ignoring `--exclude` since a single file is uploaded.")
-            if self.delete is not None and len(self.delete) > 0:
-                warnings.warn("Ignoring `--delete` since a single file is uploaded.")
-
-        if not is_xet_available() and not HF_HUB_ENABLE_HF_TRANSFER:
-            logger.info(
-                "Consider using `hf_transfer` for faster uploads. This solution comes with some limitations. See"
-                " https://huggingface.co/docs/huggingface_hub/hf_transfer for more details."
-            )
+        ),
+    ] = None,
+    commit_message: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The summary / title / first line of the generated commit.",
+        ),
+    ] = None,
+    commit_description: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The description of the generated commit.",
+        ),
+    ] = None,
+    create_pr: Annotated[
+        bool,
+        typer.Option(
+            help="Whether to upload content as a new Pull Request.",
+        ),
+    ] = False,
+    every: Annotated[
+        Optional[float],
+        typer.Option(
+            help="f set, a background job is scheduled to create commits every `every` minutes.",
+        ),
+    ] = None,
+    token: TokenOpt = None,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            help="Disable progress bars and warnings; print only the returned path.",
+        ),
+    ] = False,
+) -> None:
+    """Upload a file or a folder to the Hub. Recommended for single-commit uploads."""
+
+    if every is not None and every <= 0:
+        raise typer.BadParameter("--every must be a positive value", param_hint="every")
+
+    repo_type_str = repo_type.value
+
+    api = get_hf_api(token=token)
+
+    # Resolve local_path and path_in_repo based on implicit/explicit rules
+    resolved_local_path, resolved_path_in_repo, resolved_include = _resolve_upload_paths(
+        repo_id=repo_id, local_path=local_path, path_in_repo=path_in_repo, include=include
+    )
+
+    def run_upload() -> str:
+        if os.path.isfile(resolved_local_path):
+            if resolved_include is not None and len(resolved_include) > 0 and isinstance(resolved_include, list):
+                warnings.warn("Ignoring --include since a single file is uploaded.")
+            if exclude is not None and len(exclude) > 0:
+                warnings.warn("Ignoring --exclude since a single file is uploaded.")
+            if delete is not None and len(delete) > 0:
+                warnings.warn("Ignoring --delete since a single file is uploaded.")
 
         # Schedule commits if `every` is set
-        if self.every is not None:
-            if os.path.isfile(self.local_path):
+        if every is not None:
+            if os.path.isfile(resolved_local_path):
                 # If file => watch entire folder + use allow_patterns
-                folder_path = os.path.dirname(self.local_path)
-                path_in_repo = (
-                    self.path_in_repo[: -len(self.local_path)]  # remove filename from path_in_repo
-                    if self.path_in_repo.endswith(self.local_path)
-                    else self.path_in_repo
+                folder_path = os.path.dirname(resolved_local_path)
+                pi = (
+                    resolved_path_in_repo[: -len(resolved_local_path)]
+                    if resolved_path_in_repo.endswith(resolved_local_path)
+                    else resolved_path_in_repo
                 )
-                allow_patterns = [self.local_path]
-                ignore_patterns = []
+                allow_patterns = [resolved_local_path]
+                ignore_patterns: Optional[list[str]] = []
             else:
-                folder_path = self.local_path
-                path_in_repo = self.path_in_repo
-                allow_patterns = self.include or []
-                ignore_patterns = self.exclude or []
-                if self.delete is not None and len(self.delete) > 0:
-                    warnings.warn("Ignoring `--delete` when uploading with scheduled commits.")
+                folder_path = resolved_local_path
+                pi = resolved_path_in_repo
+                allow_patterns = (
+                    resolved_include or []
+                    if isinstance(resolved_include, list)
+                    else [resolved_include]
+                    if isinstance(resolved_include, str)
+                    else []
+                )
+                ignore_patterns = exclude or []
+                if delete is not None and len(delete) > 0:
+                    warnings.warn("Ignoring --delete when uploading with scheduled commits.")
 
             scheduler = CommitScheduler(
                 folder_path=folder_path,
-                repo_id=self.repo_id,
-                repo_type=self.repo_type,
-                revision=self.revision,
+                repo_id=repo_id,
+                repo_type=repo_type_str,
+                revision=revision,
                 allow_patterns=allow_patterns,
                 ignore_patterns=ignore_patterns,
-                path_in_repo=path_in_repo,
-                private=self.private,
-                every=self.every,
-                hf_api=self.api,
+                path_in_repo=pi,
+                private=private,
+                every=every,
+                hf_api=api,
             )
-            print(f"Scheduling commits every {self.every} minutes to {scheduler.repo_id}.")
-            try:  # Block main thread until KeyboardInterrupt
+            print(f"Scheduling commits every {every} minutes to {scheduler.repo_id}.")
+            try:
                 while True:
                     time.sleep(100)
             except KeyboardInterrupt:
@@ -265,52 +201,94 @@ class UploadCommand(BaseHuggingfaceCLICommand):
                 return "Stopped scheduled commits."
 
         # Otherwise, create repo and proceed with the upload
-        if not os.path.isfile(self.local_path) and not os.path.isdir(self.local_path):
-            raise FileNotFoundError(f"No such file or directory: '{self.local_path}'.")
-        repo_id = self.api.create_repo(
-            repo_id=self.repo_id,
-            repo_type=self.repo_type,
+        if not os.path.isfile(resolved_local_path) and not os.path.isdir(resolved_local_path):
+            raise FileNotFoundError(f"No such file or directory: '{resolved_local_path}'.")
+        created = api.create_repo(
+            repo_id=repo_id,
+            repo_type=repo_type_str,
             exist_ok=True,
-            private=self.private,
-            space_sdk="gradio" if self.repo_type == "space" else None,
+            private=private,
+            space_sdk="gradio" if repo_type_str == "space" else None,
             # ^ We don't want it to fail when uploading to a Space => let's set Gradio by default.
             # ^ I'd rather not add CLI args to set it explicitly as we already have `hf repo create` for that.
         ).repo_id
 
         # Check if branch already exists and if not, create it
-        if self.revision is not None and not self.create_pr:
+        if revision is not None and not create_pr:
             try:
-                self.api.repo_info(repo_id=repo_id, repo_type=self.repo_type, revision=self.revision)
+                api.repo_info(repo_id=created, repo_type=repo_type_str, revision=revision)
             except RevisionNotFoundError:
-                logger.info(f"Branch '{self.revision}' not found. Creating it...")
-                self.api.create_branch(repo_id=repo_id, repo_type=self.repo_type, branch=self.revision, exist_ok=True)
+                logger.info(f"Branch '{revision}' not found. Creating it...")
+                api.create_branch(repo_id=created, repo_type=repo_type_str, branch=revision, exist_ok=True)
                 # ^ `exist_ok=True` to avoid race concurrency issues
 
         # File-based upload
-        if os.path.isfile(self.local_path):
-            return self.api.upload_file(
-                path_or_fileobj=self.local_path,
-                path_in_repo=self.path_in_repo,
-                repo_id=repo_id,
-                repo_type=self.repo_type,
-                revision=self.revision,
-                commit_message=self.commit_message,
-                commit_description=self.commit_description,
-                create_pr=self.create_pr,
+        if os.path.isfile(resolved_local_path):
+            return api.upload_file(
+                path_or_fileobj=resolved_local_path,
+                path_in_repo=resolved_path_in_repo,
+                repo_id=created,
+                repo_type=repo_type_str,
+                revision=revision,
+                commit_message=commit_message,
+                commit_description=commit_description,
+                create_pr=create_pr,
             )
 
         # Folder-based upload
-        else:
-            return self.api.upload_folder(
-                folder_path=self.local_path,
-                path_in_repo=self.path_in_repo,
-                repo_id=repo_id,
-                repo_type=self.repo_type,
-                revision=self.revision,
-                commit_message=self.commit_message,
-                commit_description=self.commit_description,
-                create_pr=self.create_pr,
-                allow_patterns=self.include,
-                ignore_patterns=self.exclude,
-                delete_patterns=self.delete,
-            )
+        return api.upload_folder(
+            folder_path=resolved_local_path,
+            path_in_repo=resolved_path_in_repo,
+            repo_id=created,
+            repo_type=repo_type_str,
+            revision=revision,
+            commit_message=commit_message,
+            commit_description=commit_description,
+            create_pr=create_pr,
+            allow_patterns=(
+                resolved_include
+                if isinstance(resolved_include, list)
+                else [resolved_include]
+                if isinstance(resolved_include, str)
+                else None
+            ),
+            ignore_patterns=exclude,
+            delete_patterns=delete,
+        )
+
+    if quiet:
+        disable_progress_bars()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            print(run_upload())
+        enable_progress_bars()
+    else:
+        print(run_upload())
+        logging.set_verbosity_warning()
+
+
+def _resolve_upload_paths(
+    *, repo_id: str, local_path: Optional[str], path_in_repo: Optional[str], include: Optional[list[str]]
+) -> tuple[str, str, Optional[list[str]]]:
+    repo_name = repo_id.split("/")[-1]
+    resolved_include = include
+
+    if local_path is not None and any(c in local_path for c in ["*", "?", "["]):
+        if include is not None:
+            raise ValueError("Cannot set --include when local_path contains a wildcard.")
+        if path_in_repo is not None and path_in_repo != ".":
+            raise ValueError("Cannot set path_in_repo when local_path contains a wildcard.")
+        return ".", local_path, ["."]  # will be adjusted below; placeholder for type
+
+    if local_path is None and os.path.isfile(repo_name):
+        return repo_name, repo_name, resolved_include
+    if local_path is None and os.path.isdir(repo_name):
+        return repo_name, ".", resolved_include
+    if local_path is None:
+        raise ValueError(f"'{repo_name}' is not a local file or folder. Please set local_path explicitly.")
+
+    if path_in_repo is None and os.path.isfile(local_path):
+        return local_path, os.path.basename(local_path), resolved_include
+    if path_in_repo is None:
+        return local_path, ".", resolved_include
+    return local_path, path_in_repo, resolved_include