huggingface-hub 0.22.2__py3-none-any.whl → 0.23.1__py3-none-any.whl

huggingface_hub/_webhooks_payload.py

@@ -16,7 +16,21 @@
 
 from typing import List, Literal, Optional
 
-from pydantic import BaseModel
+from .utils import is_pydantic_available
+
+
+if is_pydantic_available():
+    from pydantic import BaseModel
+else:
+    # Define a dummy BaseModel to avoid import errors when pydantic is not installed
+    # Import error will be raised when trying to use the class
+
+    class BaseModel:  # type: ignore [no-redef]
+        def __init__(self, *args, **kwargs) -> None:
+            raise ImportError(
+                "You must have `pydantic` installed to use `WebhookPayload`. This is an optional dependency that"
+                " should be installed separately. Please run `pip install --upgrade pydantic` and retry."
+            )
 
 
 # This is an adaptation of the ReportV3 interface implemented in moon-landing. V0, V1 and V2 have been ignored as they
@@ -107,6 +121,12 @@ class WebhookPayloadRepo(ObjectId):
     url: WebhookPayloadUrl
 
 
+class WebhookPayloadUpdatedRef(BaseModel):
+    ref: str
+    oldSha: Optional[str] = None
+    newSha: Optional[str] = None
+
+
 class WebhookPayload(BaseModel):
     event: WebhookPayloadEvent
     repo: WebhookPayloadRepo
@@ -114,3 +134,4 @@ class WebhookPayload(BaseModel):
     comment: Optional[WebhookPayloadComment] = None
     webhook: WebhookPayloadWebhook
     movedTo: Optional[WebhookPayloadMovedTo] = None
+    updatedRefs: Optional[List[WebhookPayloadUpdatedRef]] = None

huggingface_hub/_webhooks_server.py

@@ -20,16 +20,19 @@ import os
 from functools import wraps
 from typing import TYPE_CHECKING, Any, Callable, Dict, Optional
 
-from .utils import experimental, is_gradio_available
-from .utils._deprecation import _deprecate_method
+from .utils import experimental, is_fastapi_available, is_gradio_available
 
 
 if TYPE_CHECKING:
     import gradio as gr
+    from fastapi import Request
 
-
-from fastapi import FastAPI, Request
-from fastapi.responses import JSONResponse
+if is_fastapi_available():
+    from fastapi import FastAPI, Request
+    from fastapi.responses import JSONResponse
+else:
+    # Will fail at runtime if FastAPI is not available
+    FastAPI = Request = JSONResponse = None  # type: ignore [misc, assignment]
 
 
 _global_app: Optional["WebhooksServer"] = None
@@ -41,7 +44,7 @@ class WebhooksServer:
     """
     The [`WebhooksServer`] class lets you create an instance of a Gradio app that can receive Huggingface webhooks.
     These webhooks can be registered using the [`~WebhooksServer.add_webhook`] decorator. Webhook endpoints are added to
-    the app as a POST endpoint to the FastAPI router. Once all the webhooks are registered, the `run` method has to be
+    the app as a POST endpoint to the FastAPI router. Once all the webhooks are registered, the `launch` method has to be
     called to start the app.
 
     It is recommended to accept [`WebhookPayload`] as the first argument of the webhook function. It is a Pydantic
@@ -87,7 +90,7 @@ class WebhooksServer:
         async def hello(payload: WebhookPayload):
             return {"message": "hello"}
 
-        app.run()
+        app.launch()
         ```
     """
 
@@ -97,6 +100,11 @@ class WebhooksServer:
                 "You must have `gradio` installed to use `WebhooksServer`. Please run `pip install --upgrade gradio`"
                 " first."
             )
+        if not is_fastapi_available():
+            raise ImportError(
+                "You must have `fastapi` installed to use `WebhooksServer`. Please run `pip install --upgrade fastapi`"
+                " first."
+            )
         return super().__new__(cls)
 
     def __init__(
@@ -134,7 +142,7 @@ class WebhooksServer:
                     # Trigger a training job if a dataset is updated
                     ...
 
-            app.run()
+            app.launch()
         ```
         """
         # Usage: directly as decorator. Example: `@app.add_webhook`
@@ -185,10 +193,6 @@ class WebhooksServer:
         if not prevent_thread_lock:
             ui.block_thread()
 
-    @_deprecate_method(version="0.23", message="Use `WebhooksServer.launch` instead.")
-    def run(self) -> None:
-        return self.launch()
-
     def _get_default_ui(self) -> "gr.Blocks":
         """Default UI if not provided (lists webhooks and provides basic instructions)."""
         import gradio as gr
@@ -278,7 +282,7 @@ def webhook_endpoint(path: Optional[str] = None) -> Callable:
                 ...
 
         # Start the server manually
-        trigger_training.run()
+        trigger_training.launch()
         ```
     """
     if callable(path):
@@ -290,16 +294,16 @@ def webhook_endpoint(path: Optional[str] = None) -> Callable:
         app = _get_global_app()
         app.add_webhook(path)(func)
         if len(app.registered_webhooks) == 1:
-            # Register `app.run` to run at exit (only once)
-            atexit.register(app.run)
+            # Register `app.launch` to run at exit (only once)
+            atexit.register(app.launch)
 
-        @wraps(app.run)
-        def _run_now():
+        @wraps(app.launch)
+        def _launch_now():
             # Run the app directly (without waiting atexit)
-            atexit.unregister(app.run)
-            app.run()
+            atexit.unregister(app.launch)
+            app.launch()
 
-        func.run = _run_now  # type: ignore
+        func.launch = _launch_now  # type: ignore
         return func
 
     return _inner

huggingface_hub/commands/download.py

@@ -38,12 +38,11 @@ Usage:
 
 import warnings
 from argparse import Namespace, _SubParsersAction
-from typing import List, Literal, Optional, Union
+from typing import List, Optional
 
 from huggingface_hub import logging
 from huggingface_hub._snapshot_download import snapshot_download
 from huggingface_hub.commands import BaseHuggingfaceCLICommand
-from huggingface_hub.constants import HF_HUB_ENABLE_HF_TRANSFER
 from huggingface_hub.file_download import hf_hub_download
 from huggingface_hub.utils import disable_progress_bars, enable_progress_bars
 
@@ -85,8 +84,7 @@ class DownloadCommand(BaseHuggingfaceCLICommand):
             "--local-dir",
             type=str,
             help=(
-                "If set, the downloaded file will be placed under this directory either as a symlink (default) or a"
-                " regular file. Check out"
+                "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."
             ),
@@ -94,13 +92,7 @@ class DownloadCommand(BaseHuggingfaceCLICommand):
         download_parser.add_argument(
             "--local-dir-use-symlinks",
             choices=["auto", "True", "False"],
-            default="auto",
-            help=(
-                "To be used with `local_dir`. If set to 'auto', the cache directory will be used and the file will be"
-                " either duplicated or symlinked to the local directory depending on its size. It set to `True`, a"
-                " symlink will be created, no matter the file size. If set to `False`, the file will either be"
-                " duplicated from cache (if already exists) or downloaded from the Hub and not cached."
-            ),
+            help=("Deprecated and ignored. Downloading to a local directory does not use symlinks anymore."),
         )
         download_parser.add_argument(
             "--force-download",
@@ -108,7 +100,9 @@ class DownloadCommand(BaseHuggingfaceCLICommand):
             help="If True, the files will be downloaded even if they are already cached.",
         )
         download_parser.add_argument(
-            "--resume-download", action="store_true", help="If True, resume a previously interrupted download."
+            "--resume-download",
+            action="store_true",
+            help="Deprecated and ignored. Downloading a file to local dir always attempts to resume previously interrupted downloads (unless hf-transfer is enabled).",
         )
         download_parser.add_argument(
             "--token", type=str, help="A User Access Token generated from https://huggingface.co/settings/tokens"
@@ -131,22 +125,13 @@ class DownloadCommand(BaseHuggingfaceCLICommand):
         self.cache_dir: Optional[str] = args.cache_dir
         self.local_dir: Optional[str] = args.local_dir
         self.force_download: bool = args.force_download
-        self.resume_download: bool = args.resume_download
+        self.resume_download: Optional[bool] = args.resume_download or None
         self.quiet: bool = args.quiet
 
-        # Raise if local_dir_use_symlinks is invalid
-        self.local_dir_use_symlinks: Union[Literal["auto"], bool]
-        use_symlinks_lowercase = args.local_dir_use_symlinks.lower()
-        if use_symlinks_lowercase == "true":
-            self.local_dir_use_symlinks = True
-        elif use_symlinks_lowercase == "false":
-            self.local_dir_use_symlinks = False
-        elif use_symlinks_lowercase == "auto":
-            self.local_dir_use_symlinks = "auto"
-        else:
-            raise ValueError(
-                f"'{args.local_dir_use_symlinks}' is not a valid value for `local_dir_use_symlinks`. It must be either"
-                " 'auto', 'True' or 'False'."
+        if args.local_dir_use_symlinks is not None:
+            warnings.warn(
+                "Ignoring --local-dir-use-symlinks. Downloading to a local directory does not use symlinks anymore.",
+                FutureWarning,
             )
 
     def run(self) -> None:
@@ -169,12 +154,6 @@ class DownloadCommand(BaseHuggingfaceCLICommand):
             if self.exclude is not None and len(self.exclude) > 0:
                 warnings.warn("Ignoring `--exclude` since filenames have being explicitly set.")
 
-        if not HF_HUB_ENABLE_HF_TRANSFER:
-            logger.info(
-                "Consider using `hf_transfer` for faster downloads. This solution comes with some limitations. See"
-                " https://huggingface.co/docs/huggingface_hub/hf_transfer for more details."
-            )
-
         # Single file to download: use `hf_hub_download`
         if len(self.filenames) == 1:
             return hf_hub_download(
@@ -187,7 +166,6 @@ class DownloadCommand(BaseHuggingfaceCLICommand):
                 force_download=self.force_download,
                 token=self.token,
                 local_dir=self.local_dir,
-                local_dir_use_symlinks=self.local_dir_use_symlinks,
                 library_name="huggingface-cli",
             )
 
@@ -210,6 +188,5 @@ class DownloadCommand(BaseHuggingfaceCLICommand):
             cache_dir=self.cache_dir,
             token=self.token,
             local_dir=self.local_dir,
-            local_dir_use_symlinks=self.local_dir_use_symlinks,
             library_name="huggingface-cli",
         )

huggingface_hub/commands/huggingface_cli.py

@@ -20,6 +20,7 @@ from huggingface_hub.commands.download import DownloadCommand
 from huggingface_hub.commands.env import EnvironmentCommand
 from huggingface_hub.commands.lfs import LfsCommands
 from huggingface_hub.commands.scan_cache import ScanCacheCommand
+from huggingface_hub.commands.tag import TagCommands
 from huggingface_hub.commands.upload import UploadCommand
 from huggingface_hub.commands.user import UserCommands
 
@@ -36,6 +37,7 @@ def main():
     LfsCommands.register_subcommand(commands_parser)
     ScanCacheCommand.register_subcommand(commands_parser)
     DeleteCacheCommand.register_subcommand(commands_parser)
+    TagCommands.register_subcommand(commands_parser)
 
     # Let's go
     args = parser.parse_args()

huggingface_hub/commands/tag.py

@@ -0,0 +1,159 @@
+# coding=utf-8
+# Copyright 2024-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 commands to perform tag management with the CLI.
+
+Usage Examples:
+    - Create a tag:
+        $ huggingface-cli tag user/my-model 1.0 --message "First release"
+        $ huggingface-cli tag user/my-model 1.0 -m "First release" --revision develop
+        $ huggingface-cli tag user/my-dataset 1.0 -m "First release" --repo-type dataset
+        $ huggingface-cli tag user/my-space 1.0
+    - List all tags:
+        $ huggingface-cli tag -l user/my-model
+        $ huggingface-cli tag --list user/my-dataset --repo-type dataset
+    - Delete a tag:
+        $ huggingface-cli tag -d user/my-model 1.0
+        $ huggingface-cli tag --delete user/my-dataset 1.0 --repo-type dataset
+        $ huggingface-cli tag -d user/my-space 1.0 -y
+"""
+
+from argparse import Namespace, _SubParsersAction
+
+from requests.exceptions import HTTPError
+
+from huggingface_hub.commands import BaseHuggingfaceCLICommand
+from huggingface_hub.constants import (
+    REPO_TYPES,
+)
+from huggingface_hub.hf_api import HfApi
+
+from ..utils import HfHubHTTPError, RepositoryNotFoundError, RevisionNotFoundError
+from ._cli_utils import ANSI
+
+
+class TagCommands(BaseHuggingfaceCLICommand):
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        tag_parser = parser.add_parser("tag", help="(create, list, delete) tags for a repo in the hub")
+
+        tag_parser.add_argument("repo_id", type=str, help="The ID of the repo to tag (e.g. `username/repo-name`).")
+        tag_parser.add_argument("tag", nargs="?", type=str, help="The name of the tag for creation or deletion.")
+        tag_parser.add_argument("-m", "--message", type=str, help="The description of the tag to create.")
+        tag_parser.add_argument("--revision", type=str, help="The git revision to tag.")
+        tag_parser.add_argument(
+            "--token", type=str, help="A User Access Token generated from https://huggingface.co/settings/tokens."
+        )
+        tag_parser.add_argument(
+            "--repo-type",
+            choices=["model", "dataset", "space"],
+            default="model",
+            help="Set the type of repository (model, dataset, or space).",
+        )
+        tag_parser.add_argument("-y", "--yes", action="store_true", help="Answer Yes to prompts automatically.")
+
+        tag_parser.add_argument("-l", "--list", action="store_true", help="List tags for a repository.")
+        tag_parser.add_argument("-d", "--delete", action="store_true", help="Delete a tag for a repository.")
+
+        tag_parser.set_defaults(func=lambda args: handle_commands(args))
+
+
+def handle_commands(args: Namespace):
+    if args.list:
+        return TagListCommand(args)
+    elif args.delete:
+        return TagDeleteCommand(args)
+    else:
+        return TagCreateCommand(args)
+
+
+class TagCommand:
+    def __init__(self, args: Namespace):
+        self.args = args
+        self.api = HfApi(token=self.args.token)
+        self.repo_id = self.args.repo_id
+        self.repo_type = self.args.repo_type
+        if self.repo_type not in REPO_TYPES:
+            print("Invalid repo --repo-type")
+            exit(1)
+
+
+class TagCreateCommand(TagCommand):
+    def run(self):
+        print(f"You are about to create tag {ANSI.bold(self.args.tag)} on {self.repo_type} {ANSI.bold(self.repo_id)}")
+
+        try:
+            self.api.create_tag(
+                repo_id=self.repo_id,
+                tag=self.args.tag,
+                tag_message=self.args.message,
+                revision=self.args.revision,
+                repo_type=self.repo_type,
+            )
+        except RepositoryNotFoundError:
+            print(f"{self.repo_type.capitalize()} {ANSI.bold(self.repo_id)} not found.")
+            exit(1)
+        except RevisionNotFoundError:
+            print(f"Revision {ANSI.bold(self.args.revision)} not found.")
+            exit(1)
+        except HfHubHTTPError as e:
+            if e.response.status_code == 409:
+                print(f"Tag {ANSI.bold(self.args.tag)} already exists on {ANSI.bold(self.repo_id)}")
+                exit(1)
+            raise e
+
+        print(f"Tag {ANSI.bold(self.args.tag)} created on {ANSI.bold(self.repo_id)}")
+
+
+class TagListCommand(TagCommand):
+    def run(self):
+        try:
+            refs = self.api.list_repo_refs(
+                repo_id=self.repo_id,
+                repo_type=self.repo_type,
+            )
+        except RepositoryNotFoundError:
+            print(f"{self.repo_type.capitalize()} {ANSI.bold(self.repo_id)} not found.")
+            exit(1)
+        except HTTPError as e:
+            print(e)
+            print(ANSI.red(e.response.text))
+            exit(1)
+        if len(refs.tags) == 0:
+            print("No tags found")
+            exit(0)
+        print(f"Tags for {self.repo_type} {ANSI.bold(self.repo_id)}:")
+        for tag in refs.tags:
+            print(tag.name)
+
+
+class TagDeleteCommand(TagCommand):
+    def run(self):
+        print(f"You are about to delete tag {ANSI.bold(self.args.tag)} on {self.repo_type} {ANSI.bold(self.repo_id)}")
+
+        if not self.args.yes:
+            choice = input("Proceed? [Y/n] ").lower()
+            if choice not in ("", "y", "yes"):
+                print("Abort")
+                exit()
+        try:
+            self.api.delete_tag(repo_id=self.repo_id, tag=self.args.tag, repo_type=self.repo_type)
+        except RepositoryNotFoundError:
+            print(f"{self.repo_type.capitalize()} {ANSI.bold(self.repo_id)} not found.")
+            exit(1)
+        except RevisionNotFoundError:
+            print(f"Tag {ANSI.bold(self.args.tag)} not found on {ANSI.bold(self.repo_id)}")
+            exit(1)
+        print(f"Tag {ANSI.bold(self.args.tag)} deleted on {ANSI.bold(self.repo_id)}")

huggingface_hub/constants.py

@@ -127,7 +127,7 @@ HF_HUB_DISABLE_TELEMETRY = (
 # `_OLD_HF_TOKEN_PATH` is deprecated and will be removed "at some point".
 # See https://github.com/huggingface/huggingface_hub/issues/1232
 _OLD_HF_TOKEN_PATH = os.path.expanduser("~/.huggingface/token")
-HF_TOKEN_PATH = os.path.join(HF_HOME, "token")
+HF_TOKEN_PATH = os.environ.get("HF_TOKEN_PATH", os.path.join(HF_HOME, "token"))
 
 
 if _staging_mode:
@@ -163,9 +163,8 @@ HF_HUB_DISABLE_IMPLICIT_TOKEN: bool = _is_true(os.environ.get("HF_HUB_DISABLE_IM
 HF_HUB_ENABLE_HF_TRANSFER: bool = _is_true(os.environ.get("HF_HUB_ENABLE_HF_TRANSFER"))
 
 
-# Used if download to `local_dir` and `local_dir_use_symlinks="auto"`
-# Files smaller than 5MB are copy-pasted while bigger files are symlinked. The idea is to save disk-usage by symlinking
-# huge files (i.e. LFS files most of the time) while allowing small files to be manually edited in local folder.
+# UNUSED
+# We don't use symlinks in local dir anymore.
 HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD: int = (
     _as_int(os.environ.get("HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD")) or 5 * 1024 * 1024
 )
@@ -197,7 +196,6 @@ ALL_INFERENCE_API_FRAMEWORKS = MAIN_INFERENCE_API_FRAMEWORKS + [
     "fastai",
     "fasttext",
     "flair",
-    "generic",
     "k2",
     "keras",
     "mindspore",

huggingface_hub/errors.py

@@ -3,6 +3,20 @@
 from requests import HTTPError
 
 
+# HEADERS ERRORS
+
+
+class LocalTokenNotFoundError(EnvironmentError):
+    """Raised if local token is required but not found."""
+
+
+# HTTP ERRORS
+
+
+class OfflineModeIsEnabled(ConnectionError):
+    """Raised when a request is made but `HF_HUB_OFFLINE=1` is set as environment variable."""
+
+
 # INFERENCE CLIENT ERRORS
 
 
@@ -10,6 +24,40 @@ class InferenceTimeoutError(HTTPError, TimeoutError):
     """Error raised when a model is unavailable or the request times out."""
 
 
+# INFERENCE ENDPOINT ERRORS
+
+
+class InferenceEndpointError(Exception):
+    """Generic exception when dealing with Inference Endpoints."""
+
+
+class InferenceEndpointTimeoutError(InferenceEndpointError, TimeoutError):
+    """Exception for timeouts while waiting for Inference Endpoint."""
+
+
+# SAFETENSORS ERRORS
+
+
+class SafetensorsParsingError(Exception):
+    """Raised when failing to parse a safetensors file metadata.
+
+    This can be the case if the file is not a safetensors file or does not respect the specification.
+    """
+
+
+class NotASafetensorsRepoError(Exception):
+    """Raised when a repo is not a Safetensors repo i.e. doesn't have either a `model.safetensors` or a
+    `model.safetensors.index.json` file.
+    """
+
+
+# TEMPLATING ERRORS
+
+
+class TemplateError(Exception):
+    """Any error raised while trying to fetch or render a chat template."""
+
+
 # TEXT GENERATION ERRORS
 
 
@@ -36,3 +84,13 @@ class IncompleteGenerationError(TextGenerationError):
 
 class UnknownError(TextGenerationError):
     pass
+
+
+# VALIDATION ERRORS
+
+
+class HFValidationError(ValueError):
+    """Generic exception thrown by `huggingface_hub` validators.
+
+    Inherits from [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError).
+    """