[hf CLI] check for updates and notify user (#3418)

* [hf CLI] check for updates and notify user

* no alpha or beta

* dirty check

* check once every 24h

* move ANSI / tabulate utils to their own module to avoid circular import issues

* do not touch installers CI

* Update src/huggingface_hub/cli/_cli_utils.py

Co-authored-by: célina <hanouticelina@gmail.com>

* docstring

* update powershell command

---------

Co-authored-by: célina <hanouticelina@gmail.com>

Author: Wauplin

.github/workflows/check-installers.yml

@@ -54,7 +54,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Run installer 
+      - name: Run installer
         shell: pwsh
         run: |
           $hfTestRoot = Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString())

docs/source/en/guides/cli.md

@@ -28,7 +28,7 @@ On macOS and Linux:
 On Windows:
 
 ```powershell
->>> powershell -c "irm https://hf.co/cli/install.ps1 | iex"
+>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
 ```
 
 Once installed, you can check that the CLI is correctly setup:

docs/source/en/installation.md

@@ -116,7 +116,7 @@ curl -LsSf https://hf.co/cli/install.sh | sh
 On Windows:
 
 ```powershell
-powershell -c "irm https://hf.co/cli/install.ps1 | iex"
+powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
 ```
 
 ## Install with conda

src/huggingface_hub/_login.py

@@ -20,8 +20,8 @@
 from typing import Optional
 
 from . import constants
-from .cli._cli_utils import ANSI
 from .utils import (
+    ANSI,
     capture_output,
     get_token,
     is_google_colab,

src/huggingface_hub/cli/_cli_utils.py

@@ -13,14 +13,21 @@
 # limitations under the License.
 """Contains CLI utilities (styling, helpers)."""
 
+import importlib.metadata
 import os
+import time
 from enum import Enum
-from typing import TYPE_CHECKING, Annotated, Optional, Union
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Optional
 
 import click
 import typer
 
-from huggingface_hub import __version__
+from huggingface_hub import __version__, constants
+from huggingface_hub.utils import ANSI, get_session, hf_raise_for_status, installation_method, logging
+
+
+logger = logging.get_logger()
 
 
 if TYPE_CHECKING:
@@ -34,58 +41,6 @@ def get_hf_api(token: Optional[str] = None) -> "HfApi":
     return HfApi(token=token, library_name="hf", library_version=__version__)
 
 
-class ANSI:
-    """
-    Helper for en.wikipedia.org/wiki/ANSI_escape_code
-    """
-
-    _bold = "\u001b[1m"
-    _gray = "\u001b[90m"
-    _red = "\u001b[31m"
-    _reset = "\u001b[0m"
-    _yellow = "\u001b[33m"
-
-    @classmethod
-    def bold(cls, s: str) -> str:
-        return cls._format(s, cls._bold)
-
-    @classmethod
-    def gray(cls, s: str) -> str:
-        return cls._format(s, cls._gray)
-
-    @classmethod
-    def red(cls, s: str) -> str:
-        return cls._format(s, cls._bold + cls._red)
-
-    @classmethod
-    def yellow(cls, s: str) -> str:
-        return cls._format(s, cls._yellow)
-
-    @classmethod
-    def _format(cls, s: str, code: str) -> str:
-        if os.environ.get("NO_COLOR"):
-            # See https://no-color.org/
-            return s
-        return f"{code}{s}{cls._reset}"
-
-
-def tabulate(rows: list[list[Union[str, int]]], headers: list[str]) -> str:
-    """
-    Inspired by:
-
-    - stackoverflow.com/a/8356620/593036
-    - stackoverflow.com/questions/9535954/printing-lists-as-tabular-data
-    """
-    col_widths = [max(len(str(x)) for x in col) for col in zip(*rows, headers)]
-    row_format = ("{{:{}}} " * len(headers)).format(*col_widths)
-    lines = []
-    lines.append(row_format.format(*headers))
-    lines.append(row_format.format(*["-" * w for w in col_widths]))
-    for row in rows:
-        lines.append(row_format.format(*row))
-    return "\n".join(lines)
-
-
 #### TYPER UTILS
 
 
@@ -150,3 +105,66 @@ class RepoType(str, Enum):
         help="Git revision id which can be a branch name, a tag, or a commit hash.",
     ),
 ]
+
+
+### PyPI VERSION CHECKER
+
+
+def check_cli_update() -> None:
+    """
+    Check whether a newer version of `huggingface_hub` is available on PyPI.
+
+    If a newer version is found, notify the user and suggest updating.
+    If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed.
+
+    This function is called at the entry point of the CLI. It only performs the check once every 24 hours, and any error
+    during the check is caught and logged, to avoid breaking the CLI.
+    """
+    try:
+        _check_cli_update()
+    except Exception:
+        # We don't want the CLI to fail on version checks, no matter the reason.
+        logger.debug("Error while checking for CLI update.", exc_info=True)
+
+
+def _check_cli_update() -> None:
+    current_version = importlib.metadata.version("huggingface_hub")
+
+    # Skip if current version is a pre-release or dev version
+    if any(tag in current_version for tag in ["rc", "dev"]):
+        return
+
+    # Skip if already checked in the last 24 hours
+    if os.path.exists(constants.CHECK_FOR_UPDATE_DONE_PATH):
+        mtime = os.path.getmtime(constants.CHECK_FOR_UPDATE_DONE_PATH)
+        if (time.time() - mtime) < 24 * 3600:
+            return
+
+    # Touch the file to mark that we did the check now
+    Path(constants.CHECK_FOR_UPDATE_DONE_PATH).touch()
+
+    # Check latest version from PyPI
+    response = get_session().get("https://pypi.org/pypi/huggingface_hub/json", timeout=2)
+    hf_raise_for_status(response)
+    data = response.json()
+    latest_version = data["info"]["version"]
+
+    # If latest version is different from current, notify user
+    if current_version != latest_version:
+        method = installation_method()
+        if method == "brew":
+            update_command = "brew upgrade huggingface-cli"
+        elif method == "hf_installer" and os.name == "nt":
+            update_command = 'powershell -NoProfile -Command "iwr -useb https://hf.co/cli/install.ps1 | iex"'
+        elif method == "hf_installer":
+            update_command = "curl -LsSf https://hf.co/cli/install.sh | sh -"
+        else:  # unknown => likely pip
+            update_command = "pip install -U huggingface_hub"
+
+        click.echo(
+            ANSI.yellow(
+                f"A new version of huggingface_hub ({latest_version}) is available! "
+                f"You are using version {current_version}.\n"
+                f"To update, run: {ANSI.bold(update_command)}\n",
+            )
+        )

src/huggingface_hub/cli/auth.py

@@ -39,8 +39,8 @@
 from huggingface_hub.hf_api import whoami
 
 from .._login import auth_list, auth_switch, login, logout
-from ..utils import get_stored_tokens, get_token, logging
-from ._cli_utils import ANSI, TokenOpt, typer_factory
+from ..utils import ANSI, get_stored_tokens, get_token, logging
+from ._cli_utils import TokenOpt, typer_factory
 
 
 logger = logging.get_logger(__name__)

src/huggingface_hub/cli/cache.py

@@ -23,8 +23,8 @@
 
 import typer
 
-from ..utils import CachedRepoInfo, CachedRevisionInfo, CacheNotFound, HFCacheInfo, scan_cache_dir
-from ._cli_utils import ANSI, tabulate, typer_factory
+from ..utils import ANSI, CachedRepoInfo, CachedRevisionInfo, CacheNotFound, HFCacheInfo, scan_cache_dir, tabulate
+from ._cli_utils import typer_factory
 
 
 # --- DELETE helpers (from delete_cache.py) ---

src/huggingface_hub/cli/download.py

@@ -44,9 +44,9 @@
 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
+from huggingface_hub.utils import _format_size, disable_progress_bars, enable_progress_bars, tabulate
 
-from ._cli_utils import RepoIdArg, RepoTypeOpt, RevisionOpt, TokenOpt, tabulate
+from ._cli_utils import RepoIdArg, RepoTypeOpt, RevisionOpt, TokenOpt
 
 
 logger = logging.get_logger(__name__)

src/huggingface_hub/cli/hf.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-from huggingface_hub.cli._cli_utils import typer_factory
+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
@@ -52,6 +52,7 @@
 
 def main():
     logging.set_verbosity_info()
+    check_cli_update()
     app()
 
 

src/huggingface_hub/cli/repo.py

@@ -27,10 +27,9 @@
 import typer
 
 from huggingface_hub.errors import HfHubHTTPError, RepositoryNotFoundError, RevisionNotFoundError
-from huggingface_hub.utils import logging
+from huggingface_hub.utils import ANSI, logging
 
 from ._cli_utils import (
-    ANSI,
     PrivateOpt,
     RepoIdArg,
     RepoType,