Refactor CLI implementation using Typer (#3372)

* Refactor CLI implementation using Typer (#3365)

* migrate CLI to typer

* (#3364) disable rich in all cases

* update tests

* make typer-slim a required dep

* use Annotated

* fix linting issues

* fix tests

* refactoring

* update docs

* use built in types

* fix mypy

* call whoami directly

* lint

* Apply suggestions from code review

Co-authored-by: Lucain <lucain@huggingface.co>

* import Annotated from typing

* Use Enums

* set verbosity globally

* refactor scan cache and update version docstring

* centralize where Typer is defined

* no need for ...

* rename enum

* no need for extra param name

* docstring

* revert

* centralize arguments and options definition

* add library version when initializing HfApi

* add auto-completion

* sort commands alphabetically

* suggestions

* centralize jobs params and HfApi initialization

* fix

---------

Co-authored-by: Lucain <lucain@huggingface.co>

* update docs

---------

Co-authored-by: Lucain <lucain@huggingface.co>

Author: hanouticelina

docs/source/en/guides/cli.md

@@ -24,24 +24,27 @@ Once installed, you can check that the CLI is correctly setup:
 
 ```
 >>> hf --help
-usage: hf <command> [<args>]
-
-positional arguments:
-  {auth,cache,download,repo,repo-files,upload,upload-large-folder,env,version,lfs-enable-largefiles,lfs-multipart-upload}
-                        hf command helpers
-    auth                Manage authentication (login, logout, etc.).
-    cache               Manage local cache directory.
-    download            Download files from the Hub
-    repo                Manage repos on the Hub.
-    repo-files          Manage files in a repo on the Hub.
-    upload              Upload a file or a folder to the Hub. Recommended for single-commit uploads.
-    upload-large-folder
-                        Upload a large folder to the Hub. Recommended for resumable uploads.
-    env                 Print information about the environment.
-    version             Print information about the hf version.
-
-options:
-  -h, --help            show this help message and exit
+Usage: hf [OPTIONS] COMMAND [ARGS]...
+
+  Hugging Face Hub CLI
+
+Options:
+  --install-completion  Install completion for the current shell.
+  --show-completion     Show completion for the current shell, to copy it or
+                        customize the installation.
+  --help                Show this message and exit.
+
+Commands:
+  auth                 Manage authentication (login, logout, etc.).
+  cache                Manage local cache directory.
+  download             Download files from the Hub.
+  env                  Print information about the environment.
+  jobs                 Run and manage Jobs on the Hub.
+  repo                 Manage repos on the Hub.
+  repo-files           Manage files in a repo on the Hub.
+  upload               Upload a file or a folder to the Hub.
+  upload-large-folder  Upload a large folder to the Hub.
+  version              Print information about the hf version.
 ```
 
 If the CLI is correctly installed, you should see a list of all the options available in the CLI. If you get an error message such as `command not found: hf`, please refer to the [Installation](../installation) guide.

setup.py

@@ -21,13 +21,15 @@ def get_version() -> str:
     "pyyaml>=5.1",
     "httpx>=0.23.0, <1",
     "tqdm>=4.42.1",
+    "typer-slim",
     "typing-extensions>=3.7.4.3",  # to be able to import TypeAlias
 ]
 
 extras = {}
 
 extras["cli"] = [
     "InquirerPy==0.3.4",  # Note: installs `prompt-toolkit` in the background
+    "shellingham",
 ]
 
 extras["inference"] = [

src/huggingface_hub/cli/__init__.py

@@ -11,17 +11,3 @@
 # 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 abc import ABC, abstractmethod
-from argparse import _SubParsersAction
-
-
-class BaseHuggingfaceCLICommand(ABC):
-    @staticmethod
-    @abstractmethod
-    def register_subcommand(parser: _SubParsersAction):
-        raise NotImplementedError()
-
-    @abstractmethod
-    def run(self):
-        raise NotImplementedError()

src/huggingface_hub/cli/_cli_utils.py

@@ -11,10 +11,17 @@
 # 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 a utility for good-looking prints."""
+"""Contains CLI utilities (styling, helpers)."""
 
 import os
-from typing import Union
+from enum import Enum
+from typing import Annotated, Optional, Union
+
+import click
+import typer
+
+from huggingface_hub import __version__
+from huggingface_hub.hf_api import HfApi
 
 
 class ANSI:
@@ -67,3 +74,73 @@ def tabulate(rows: list[list[Union[str, int]]], headers: list[str]) -> str:
     for row in rows:
         lines.append(row_format.format(*row))
     return "\n".join(lines)
+
+
+#### TYPER UTILS
+
+
+class AlphabeticalMixedGroup(typer.core.TyperGroup):
+    """
+    Typer Group that lists commands and sub-apps mixed and alphabetically.
+    """
+
+    def list_commands(self, ctx: click.Context) -> list[str]:  # type: ignore[name-defined]
+        # click.Group stores both commands and sub-groups in `self.commands`
+        return sorted(self.commands.keys())
+
+
+def typer_factory(help: str) -> typer.Typer:
+    return typer.Typer(
+        help=help,
+        add_completion=True,
+        rich_markup_mode=None,
+        no_args_is_help=True,
+        cls=AlphabeticalMixedGroup,
+    )
+
+
+class RepoType(str, Enum):
+    model = "model"
+    dataset = "dataset"
+    space = "space"
+
+
+RepoIdArg = Annotated[
+    str,
+    typer.Argument(
+        help="The ID of the repo (e.g. `username/repo-name`).",
+    ),
+]
+
+
+RepoTypeOpt = Annotated[
+    RepoType,
+    typer.Option(
+        help="The type of repository (model, dataset, or space).",
+    ),
+]
+
+TokenOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="A User Access Token generated from https://huggingface.co/settings/tokens.",
+    ),
+]
+
+PrivateOpt = Annotated[
+    bool,
+    typer.Option(
+        help="Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists.",
+    ),
+]
+
+RevisionOpt = Annotated[
+    Optional[str],
+    typer.Option(
+        help="Git revision id which can be a branch name, a tag, or a commit hash.",
+    ),
+]
+
+
+def get_hf_api(token: Optional[str] = None) -> HfApi:
+    return HfApi(token=token, library_name="hf", library_version=__version__)