huggingface-hub 0.22.2__tar.gz → 0.23.0__tar.gz

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: huggingface_hub
-Version: 0.22.2
+Version: 0.23.0
 Summary: Client library to download and publish models, datasets and other repos on the huggingface.co hub
 Home-page: https://github.com/huggingface/huggingface_hub
 Author: Hugging Face, Inc.
@@ -63,6 +63,7 @@ License-File: LICENSE
         <a href="https://github.com/huggingface/huggingface_hub/blob/main/README_cn.md">中文（简体）</a>
     <p>
 </h4>
+
 ---
 
 **Documentation**: <a href="https://hf.co/docs/huggingface_hub" target="_blank">https://hf.co/docs/huggingface_hub</a>

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/README.md

@@ -25,6 +25,7 @@
         <a href="https://github.com/huggingface/huggingface_hub/blob/main/README_cn.md">中文（简体）</a>
     <p>
 </h4>
+
 ---
 
 **Documentation**: <a href="https://hf.co/docs/huggingface_hub" target="_blank">https://hf.co/docs/huggingface_hub</a>

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/setup.py

@@ -75,6 +75,7 @@ extras["testing"] = (
         "Pillow",
         "gradio",  # to test webhooks
         "numpy",  # for embeddings
+        "fastapi",  # To build the documentation
     ]
 )
 

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/src/huggingface_hub/__init__.py

@@ -46,7 +46,7 @@ import sys
 from typing import TYPE_CHECKING
 
 
-__version__ = "0.22.2"
+__version__ = "0.23.0"
 
 # Alphabetical order of definitions is ensured in tests
 # WARNING: any comment added in this dictionary definition will be lost when
@@ -198,7 +198,6 @@ _SUBMOD_ATTRS = {
         "list_accepted_access_requests",
         "list_collections",
         "list_datasets",
-        "list_files_info",
         "list_inference_endpoints",
         "list_liked_repos",
         "list_metrics",
@@ -271,13 +270,28 @@ _SUBMOD_ATTRS = {
         "AutomaticSpeechRecognitionOutputChunk",
         "AutomaticSpeechRecognitionParameters",
         "ChatCompletionInput",
+        "ChatCompletionInputFunctionDefinition",
         "ChatCompletionInputMessage",
+        "ChatCompletionInputTool",
+        "ChatCompletionInputToolCall",
+        "ChatCompletionInputToolTypeClass",
         "ChatCompletionOutput",
-        "ChatCompletionOutputChoice",
-        "ChatCompletionOutputChoiceMessage",
+        "ChatCompletionOutputComplete",
+        "ChatCompletionOutputFunctionDefinition",
+        "ChatCompletionOutputLogprob",
+        "ChatCompletionOutputLogprobs",
+        "ChatCompletionOutputMessage",
+        "ChatCompletionOutputToolCall",
+        "ChatCompletionOutputTopLogprob",
+        "ChatCompletionOutputUsage",
         "ChatCompletionStreamOutput",
         "ChatCompletionStreamOutputChoice",
         "ChatCompletionStreamOutputDelta",
+        "ChatCompletionStreamOutputDeltaToolCall",
+        "ChatCompletionStreamOutputFunction",
+        "ChatCompletionStreamOutputLogprob",
+        "ChatCompletionStreamOutputLogprobs",
+        "ChatCompletionStreamOutputTopLogprob",
         "DepthEstimationInput",
         "DepthEstimationOutput",
         "DocumentQuestionAnsweringInput",
@@ -325,14 +339,16 @@ _SUBMOD_ATTRS = {
         "TextClassificationOutputElement",
         "TextClassificationParameters",
         "TextGenerationInput",
+        "TextGenerationInputGenerateParameters",
+        "TextGenerationInputGrammarType",
         "TextGenerationOutput",
+        "TextGenerationOutputBestOfSequence",
         "TextGenerationOutputDetails",
-        "TextGenerationOutputSequenceDetails",
+        "TextGenerationOutputPrefillToken",
         "TextGenerationOutputToken",
-        "TextGenerationParameters",
-        "TextGenerationPrefillToken",
-        "TextGenerationStreamDetails",
         "TextGenerationStreamOutput",
+        "TextGenerationStreamOutputStreamDetails",
+        "TextGenerationStreamOutputToken",
         "TextToAudioGenerationParameters",
         "TextToAudioInput",
         "TextToAudioOutput",
@@ -501,15 +517,15 @@ def _attach(package_name, submodules=None, submod_attrs=None):
     def __dir__():
         return __all__
 
-    if os.environ.get("EAGER_IMPORT", ""):
-        for attr in set(attr_to_modules.keys()) | submodules:
-            __getattr__(attr)
-
     return __getattr__, __dir__, list(__all__)
 
 
 __getattr__, __dir__, __all__ = _attach(__name__, submodules=[], submod_attrs=_SUBMOD_ATTRS)
 
+if os.environ.get("EAGER_IMPORT", ""):
+    for attr in __all__:
+        __getattr__(attr)
+
 # WARNING: any content below this statement is generated automatically. Any manual edit
 # will be lost when re-generating this file !
 #
@@ -662,7 +678,6 @@ if TYPE_CHECKING:  # pragma: no cover
         list_accepted_access_requests,  # noqa: F401
         list_collections,  # noqa: F401
         list_datasets,  # noqa: F401
-        list_files_info,  # noqa: F401
         list_inference_endpoints,  # noqa: F401
         list_liked_repos,  # noqa: F401
         list_metrics,  # noqa: F401
@@ -733,13 +748,28 @@ if TYPE_CHECKING:  # pragma: no cover
         AutomaticSpeechRecognitionOutputChunk,  # noqa: F401
         AutomaticSpeechRecognitionParameters,  # noqa: F401
         ChatCompletionInput,  # noqa: F401
+        ChatCompletionInputFunctionDefinition,  # noqa: F401
         ChatCompletionInputMessage,  # noqa: F401
+        ChatCompletionInputTool,  # noqa: F401
+        ChatCompletionInputToolCall,  # noqa: F401
+        ChatCompletionInputToolTypeClass,  # noqa: F401
         ChatCompletionOutput,  # noqa: F401
-        ChatCompletionOutputChoice,  # noqa: F401
-        ChatCompletionOutputChoiceMessage,  # noqa: F401
+        ChatCompletionOutputComplete,  # noqa: F401
+        ChatCompletionOutputFunctionDefinition,  # noqa: F401
+        ChatCompletionOutputLogprob,  # noqa: F401
+        ChatCompletionOutputLogprobs,  # noqa: F401
+        ChatCompletionOutputMessage,  # noqa: F401
+        ChatCompletionOutputToolCall,  # noqa: F401
+        ChatCompletionOutputTopLogprob,  # noqa: F401
+        ChatCompletionOutputUsage,  # noqa: F401
         ChatCompletionStreamOutput,  # noqa: F401
         ChatCompletionStreamOutputChoice,  # noqa: F401
         ChatCompletionStreamOutputDelta,  # noqa: F401
+        ChatCompletionStreamOutputDeltaToolCall,  # noqa: F401
+        ChatCompletionStreamOutputFunction,  # noqa: F401
+        ChatCompletionStreamOutputLogprob,  # noqa: F401
+        ChatCompletionStreamOutputLogprobs,  # noqa: F401
+        ChatCompletionStreamOutputTopLogprob,  # noqa: F401
         DepthEstimationInput,  # noqa: F401
         DepthEstimationOutput,  # noqa: F401
         DocumentQuestionAnsweringInput,  # noqa: F401
@@ -787,14 +817,16 @@ if TYPE_CHECKING:  # pragma: no cover
         TextClassificationOutputElement,  # noqa: F401
         TextClassificationParameters,  # noqa: F401
         TextGenerationInput,  # noqa: F401
+        TextGenerationInputGenerateParameters,  # noqa: F401
+        TextGenerationInputGrammarType,  # noqa: F401
         TextGenerationOutput,  # noqa: F401
+        TextGenerationOutputBestOfSequence,  # noqa: F401
         TextGenerationOutputDetails,  # noqa: F401
-        TextGenerationOutputSequenceDetails,  # noqa: F401
+        TextGenerationOutputPrefillToken,  # noqa: F401
         TextGenerationOutputToken,  # noqa: F401
-        TextGenerationParameters,  # noqa: F401
-        TextGenerationPrefillToken,  # noqa: F401
-        TextGenerationStreamDetails,  # noqa: F401
         TextGenerationStreamOutput,  # noqa: F401
+        TextGenerationStreamOutputStreamDetails,  # noqa: F401
+        TextGenerationStreamOutputToken,  # noqa: F401
         TextToAudioGenerationParameters,  # noqa: F401
         TextToAudioInput,  # noqa: F401
         TextToAudioOutput,  # noqa: F401

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/src/huggingface_hub/_commit_api.py

@@ -15,14 +15,14 @@ from typing import TYPE_CHECKING, Any, BinaryIO, Dict, Iterable, Iterator, List,
 
 from tqdm.contrib.concurrent import thread_map
 
-from huggingface_hub import get_session
-
 from .constants import ENDPOINT, HF_HUB_ENABLE_HF_TRANSFER
 from .file_download import hf_hub_url
 from .lfs import UploadInfo, lfs_upload, post_lfs_batch_info
 from .utils import (
+    FORBIDDEN_FOLDERS,
     EntryNotFoundError,
     chunk_iterable,
+    get_session,
     hf_raise_for_status,
     logging,
     tqdm_stream_file,
@@ -255,11 +255,12 @@ def _validate_path_in_repo(path_in_repo: str) -> str:
         raise ValueError(f"Invalid `path_in_repo` in CommitOperation: '{path_in_repo}'")
     if path_in_repo.startswith("./"):
         path_in_repo = path_in_repo[2:]
-    if any(part == ".git" for part in path_in_repo.split("/")):
-        raise ValueError(
-            "Invalid `path_in_repo` in CommitOperation: cannot update files under a '.git/' folder (path:"
-            f" '{path_in_repo}')."
-        )
+    for forbidden in FORBIDDEN_FOLDERS:
+        if any(part == forbidden for part in path_in_repo.split("/")):
+            raise ValueError(
+                f"Invalid `path_in_repo` in CommitOperation: cannot update files under a '{forbidden}/' folder (path:"
+                f" '{path_in_repo}')."
+            )
     return path_in_repo
 
 
@@ -405,7 +406,7 @@ def _upload_lfs_files(
 
     if HF_HUB_ENABLE_HF_TRANSFER:
         logger.debug(f"Uploading {len(filtered_actions)} LFS files to the Hub using `hf_transfer`.")
-        for action in hf_tqdm(filtered_actions):
+        for action in hf_tqdm(filtered_actions, name="huggingface_hub.lfs_upload"):
             _wrapped_lfs_upload(action)
     elif len(filtered_actions) == 1:
         logger.debug("Uploading 1 LFS file to the Hub")

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/src/huggingface_hub/_commit_scheduler.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from threading import Lock, Thread
 from typing import Dict, List, Optional, Union
 
-from .hf_api import IGNORE_GIT_FOLDER_PATTERNS, CommitInfo, CommitOperationAdd, HfApi
+from .hf_api import DEFAULT_IGNORE_PATTERNS, CommitInfo, CommitOperationAdd, HfApi
 from .utils import filter_repo_objects
 
 
@@ -107,7 +107,7 @@ class CommitScheduler:
             ignore_patterns = []
         elif isinstance(ignore_patterns, str):
             ignore_patterns = [ignore_patterns]
-        self.ignore_patterns = ignore_patterns + IGNORE_GIT_FOLDER_PATTERNS
+        self.ignore_patterns = ignore_patterns + DEFAULT_IGNORE_PATTERNS
 
         if self.folder_path.is_file():
             raise ValueError(f"'folder_path' must be a directory, not a file: '{self.folder_path}'.")

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/src/huggingface_hub/_inference_endpoints.py

@@ -4,9 +4,11 @@ from datetime import datetime
 from enum import Enum
 from typing import TYPE_CHECKING, Dict, Optional, Union
 
+from huggingface_hub.errors import InferenceEndpointError, InferenceEndpointTimeoutError
+
 from .inference._client import InferenceClient
 from .inference._generated._async_client import AsyncInferenceClient
-from .utils import logging, parse_datetime
+from .utils import get_session, logging, parse_datetime
 
 
 if TYPE_CHECKING:
@@ -16,14 +18,6 @@ if TYPE_CHECKING:
 logger = logging.get_logger(__name__)
 
 
-class InferenceEndpointError(Exception):
-    """Generic exception when dealing with Inference Endpoints."""
-
-
-class InferenceEndpointTimeoutError(InferenceEndpointError, TimeoutError):
-    """Exception for timeouts while waiting for Inference Endpoint."""
-
-
 class InferenceEndpointStatus(str, Enum):
     PENDING = "pending"
     INITIALIZING = "initializing"
@@ -200,10 +194,6 @@ class InferenceEndpoint:
             [`InferenceEndpointTimeoutError`]
                 If the Inference Endpoint is not deployed after `timeout` seconds.
         """
-        if self.url is not None:  # Means the endpoint is deployed
-            logger.info("Inference Endpoint is ready to be used.")
-            return self
-
         if timeout is not None and timeout < 0:
             raise ValueError("`timeout` cannot be negative.")
         if refresh_every <= 0:
@@ -211,10 +201,12 @@ class InferenceEndpoint:
 
         start = time.time()
         while True:
-            self.fetch()
-            if self.url is not None:  # Means the endpoint is deployed
-                logger.info("Inference Endpoint is ready to be used.")
-                return self
+            if self.url is not None:
+                # Means the URL is provisioned => check if the endpoint is reachable
+                response = get_session().get(self.url, headers=self._api._build_hf_headers(token=self._token))
+                if response.status_code == 200:
+                    logger.info("Inference Endpoint is ready to be used.")
+                    return self
             if self.status == InferenceEndpointStatus.FAILED:
                 raise InferenceEndpointError(
                     f"Inference Endpoint {self.name} failed to deploy. Please check the logs for more information."
@@ -224,6 +216,7 @@ class InferenceEndpoint:
                     raise InferenceEndpointTimeoutError("Timeout while waiting for Inference Endpoint to be deployed.")
             logger.info(f"Inference Endpoint is not deployed yet ({self.status}). Waiting {refresh_every}s...")
             time.sleep(refresh_every)
+            self.fetch()
 
     def fetch(self) -> "InferenceEndpoint":
         """Fetch latest information about the Inference Endpoint.

huggingface_hub-0.23.0/src/huggingface_hub/_local_folder.py

@@ -0,0 +1,229 @@
+# 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 utilities to handle the `../.huggingface` folder in local directories.
+
+First discussed in https://github.com/huggingface/huggingface_hub/issues/1738 to store
+download metadata when downloading files from the hub to a local directory (without
+using the cache).
+
+./.huggingface folder structure:
+[4.0K]  data
+├── [4.0K]  .huggingface
+│   └── [4.0K]  download
+│       ├── [  16]  file.parquet.metadata
+│       ├── [  16]  file.txt.metadata
+│       └── [4.0K]  folder
+│           └── [  16]  file.parquet.metadata
+│
+├── [6.5G]  file.parquet
+├── [1.5K]  file.txt
+└── [4.0K]  folder
+    └── [   16]  file.parquet
+
+
+Metadata file structure:
+```
+# file.txt.metadata
+11c5a3d5811f50298f278a704980280950aedb10
+a16a55fda99d2f2e7b69cce5cf93ff4ad3049930
+1712656091.123
+
+# file.parquet.metadata
+11c5a3d5811f50298f278a704980280950aedb10
+7c5d3f4b8b76583b422fcb9189ad6c89d5d97a094541ce8932dce3ecabde1421
+1712656091.123
+}
+```
+"""
+
+import logging
+import os
+import time
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+from .utils import WeakFileLock
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LocalDownloadFilePaths:
+    """
+    Paths to the files related to a download process in a local dir.
+
+    Returned by `get_local_download_paths`.
+
+    Attributes:
+        file_path (`Path`):
+            Path where the file will be saved.
+        lock_path (`Path`):
+            Path to the lock file used to ensure atomicity when reading/writing metadata.
+        metadata_path (`Path`):
+            Path to the metadata file.
+    """
+
+    file_path: Path
+    lock_path: Path
+    metadata_path: Path
+
+    def incomplete_path(self, etag: str) -> Path:
+        """Return the path where a file will be temporarily downloaded before being moved to `file_path`."""
+        return self.metadata_path.with_suffix(f".{etag}.incomplete")
+
+
+@dataclass
+class LocalDownloadFileMetadata:
+    """
+    Metadata about a file in the local directory related to a download process.
+
+    Attributes:
+        filename (`str`):
+            Path of the file in the repo.
+        commit_hash (`str`):
+            Commit hash of the file in the repo.
+        etag (`str`):
+            ETag of the file in the repo. Used to check if the file has changed.
+            For LFS files, this is the sha256 of the file. For regular files, it corresponds to the git hash.
+        timestamp (`int`):
+            Unix timestamp of when the metadata was saved i.e. when the metadata was accurate.
+    """
+
+    filename: str
+    commit_hash: str
+    etag: str
+    timestamp: float
+
+
+@lru_cache(maxsize=128)  # ensure singleton
+def get_local_download_paths(local_dir: Path, filename: str) -> LocalDownloadFilePaths:
+    """Compute paths to the files related to a download process.
+
+    Folders containing the paths are all guaranteed to exist.
+
+    Args:
+        local_dir (`Path`):
+            Path to the local directory in which files are downloaded.
+        filename (`str`):
+            Path of the file in the repo.
+
+    Return:
+        [`LocalDownloadFilePaths`]: the paths to the files (file_path, lock_path, metadata_path, incomplete_path).
+    """
+    # filename is the path in the Hub repository (separated by '/')
+    # make sure to have a cross platform transcription
+    sanitized_filename = os.path.join(*filename.split("/"))
+    if os.name == "nt":
+        if sanitized_filename.startswith("..\\") or "\\..\\" in sanitized_filename:
+            raise ValueError(
+                f"Invalid filename: cannot handle filename '{sanitized_filename}' on Windows. Please ask the repository"
+                " owner to rename this file."
+            )
+    file_path = local_dir / sanitized_filename
+    metadata_path = _huggingface_dir(local_dir) / "download" / f"{sanitized_filename}.metadata"
+    lock_path = metadata_path.with_suffix(".lock")
+
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    metadata_path.parent.mkdir(parents=True, exist_ok=True)
+    return LocalDownloadFilePaths(file_path=file_path, lock_path=lock_path, metadata_path=metadata_path)
+
+
+def read_download_metadata(local_dir: Path, filename: str) -> Optional[LocalDownloadFileMetadata]:
+    """Read metadata about a file in the local directory related to a download process.
+
+    Args:
+        local_dir (`Path`):
+            Path to the local directory in which files are downloaded.
+        filename (`str`):
+            Path of the file in the repo.
+
+    Return:
+        `[LocalDownloadFileMetadata]` or `None`: the metadata if it exists, `None` otherwise.
+    """
+    paths = get_local_download_paths(local_dir, filename)
+    # file_path = local_file_path(local_dir, filename)
+    # lock_path, metadata_path = _download_metadata_file_path(local_dir, filename)
+    with WeakFileLock(paths.lock_path):
+        if paths.metadata_path.exists():
+            try:
+                with paths.metadata_path.open() as f:
+                    commit_hash = f.readline().strip()
+                    etag = f.readline().strip()
+                    timestamp = float(f.readline().strip())
+                    metadata = LocalDownloadFileMetadata(
+                        filename=filename,
+                        commit_hash=commit_hash,
+                        etag=etag,
+                        timestamp=timestamp,
+                    )
+            except Exception as e:
+                # remove the metadata file if it is corrupted / not the right format
+                logger.warning(
+                    f"Invalid metadata file {paths.metadata_path}: {e}. Removing it from disk and continue."
+                )
+                try:
+                    paths.metadata_path.unlink()
+                except Exception as e:
+                    logger.warning(f"Could not remove corrupted metadata file {paths.metadata_path}: {e}")
+
+            try:
+                # check if the file exists and hasn't been modified since the metadata was saved
+                stat = paths.file_path.stat()
+                if (
+                    stat.st_mtime - 1 <= metadata.timestamp
+                ):  # allow 1s difference as stat.st_mtime might not be precise
+                    return metadata
+                logger.info(f"Ignored metadata for '{filename}' (outdated). Will re-compute hash.")
+            except FileNotFoundError:
+                # file does not exist => metadata is outdated
+                return None
+    return None
+
+
+def write_download_metadata(local_dir: Path, filename: str, commit_hash: str, etag: str) -> None:
+    """Write metadata about a file in the local directory related to a download process.
+
+    Args:
+        local_dir (`Path`):
+            Path to the local directory in which files are downloaded.
+    """
+    paths = get_local_download_paths(local_dir, filename)
+    with WeakFileLock(paths.lock_path):
+        with paths.metadata_path.open("w") as f:
+            f.write(f"{commit_hash}\n{etag}\n{time.time()}\n")
+
+
+@lru_cache()
+def _huggingface_dir(local_dir: Path) -> Path:
+    """Return the path to the `.huggingface` directory in a local directory."""
+    # Wrap in lru_cache to avoid overwriting the .gitignore file if called multiple times
+    path = local_dir / ".huggingface"
+    path.mkdir(exist_ok=True, parents=True)
+
+    # Create a .gitignore file in the .huggingface directory if it doesn't exist
+    # Should be thread-safe enough like this.
+    gitignore = path / ".gitignore"
+    gitignore_lock = path / ".gitignore.lock"
+    if not gitignore.exists():
+        with WeakFileLock(gitignore_lock):
+            gitignore.write_text("*")
+        try:
+            gitignore_lock.unlink()
+        except OSError:  # FileNotFoundError, PermissionError, etc.
+            pass
+    return path

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/src/huggingface_hub/_login.py

@@ -103,9 +103,10 @@ def login(
     if token is not None:
         if not add_to_git_credential:
             print(
-                "Token has not been saved to git credential helper. Pass"
-                " `add_to_git_credential=True` if you want to set the git"
-                " credential as well."
+                "The token has not been saved to the git credentials helper. Pass "
+                "`add_to_git_credential=True` in this function directly or "
+                "`--add-to-git-credential` if using via `huggingface-cli` if "
+                "you want to set the git credential as well."
             )
         _login(token, add_to_git_credential=add_to_git_credential, write_permission=write_permission)
     elif is_notebook():

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/src/huggingface_hub/_multi_commits.py

@@ -273,8 +273,8 @@ def multi_commit_create_pull_request(
     commit_message: str,
     commit_description: Optional[str],
     strategy: MultiCommitStrategy,
-    token: Optional[str],
     repo_type: Optional[str],
+    token: Union[str, bool, None] = None,
 ) -> DiscussionWithDetails:
     return api.create_pull_request(
         repo_id=repo_id,

{huggingface_hub-0.22.2 → huggingface_hub-0.23.0}/src/huggingface_hub/_snapshot_download.py

@@ -39,13 +39,11 @@ def snapshot_download(
     revision: Optional[str] = None,
     cache_dir: Union[str, Path, None] = None,
     local_dir: Union[str, Path, None] = None,
-    local_dir_use_symlinks: Union[bool, Literal["auto"]] = "auto",
     library_name: Optional[str] = None,
     library_version: Optional[str] = None,
     user_agent: Optional[Union[Dict, str]] = None,
     proxies: Optional[Dict] = None,
     etag_timeout: float = DEFAULT_ETAG_TIMEOUT,
-    resume_download: bool = False,
     force_download: bool = False,
     token: Optional[Union[bool, str]] = None,
     local_files_only: bool = False,
@@ -55,6 +53,9 @@ def snapshot_download(
     tqdm_class: Optional[base_tqdm] = None,
     headers: Optional[Dict[str, str]] = None,
     endpoint: Optional[str] = None,
+    # Deprecated args
+    local_dir_use_symlinks: Union[bool, Literal["auto"]] = "auto",
+    resume_download: Optional[bool] = None,
 ) -> str:
     """Download repo files.
 
@@ -63,20 +64,10 @@ def snapshot_download(
     to keep their actual filename relative to that folder. You can also filter which files to download using
     `allow_patterns` and `ignore_patterns`.
 
-    If `local_dir` is provided, the file structure from the repo will be replicated in this location. You can configure
-    how you want to move those files:
-      - If `local_dir_use_symlinks="auto"` (default), files are downloaded and stored in the cache directory as blob
-        files. Small files (<5MB) are duplicated in `local_dir` while a symlink is created for bigger files. The goal
-        is to be able to manually edit and save small files without corrupting the cache while saving disk space for
-        binary files. The 5MB threshold can be configured with the `HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`
-        environment variable.
-      - If `local_dir_use_symlinks=True`, files are downloaded, stored in the cache directory and symlinked in `local_dir`.
-        This is optimal in term of disk usage but files must not be manually edited.
-      - If `local_dir_use_symlinks=False` and the blob files exist in the cache directory, they are duplicated in the
-        local dir. This means disk usage is not optimized.
-      - Finally, if `local_dir_use_symlinks=False` and the blob files do not exist in the cache directory, then the
-        files are downloaded and directly placed under `local_dir`. This means if you need to download them again later,
-        they will be re-downloaded entirely.
+    If `local_dir` is provided, the file structure from the repo will be replicated in this location. When using this
+    option, the `cache_dir` will not be used and a `.huggingface/` folder will be created at the root of `local_dir`
+    to store some metadata related to the downloaded files. While this mechanism is not as robust as the main
+    cache-system, it's optimized for regularly pulling the latest version of a repository.
 
     An alternative would be to clone the repo but this requires git and git-lfs to be installed and properly
     configured. It is also not possible to filter which files to download when cloning a repository using git.
@@ -93,13 +84,7 @@ def snapshot_download(
         cache_dir (`str`, `Path`, *optional*):
             Path to the folder where cached files are stored.
         local_dir (`str` or `Path`, *optional*):
-            If provided, the downloaded files will be placed under this directory, either as symlinks (default) or
-            regular files (see description for more details).
-        local_dir_use_symlinks (`"auto"` or `bool`, defaults to `"auto"`):
-            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. See description for more details.
+            If provided, the downloaded files will be placed under this directory.
         library_name (`str`, *optional*):
             The name of the library to which the object corresponds.
         library_version (`str`, *optional*):
@@ -112,8 +97,6 @@ def snapshot_download(
         etag_timeout (`float`, *optional*, defaults to `10`):
             When fetching ETag, how many seconds to wait for the server to send
             data before giving up which is passed to `requests.request`.
-        resume_download (`bool`, *optional*, defaults to `False):
-            If `True`, resume a previously interrupted download.
         force_download (`bool`, *optional*, defaults to `False`):
             Whether the file should be downloaded even if it already exists in the local cache.
         token (`str`, `bool`, *optional*):
@@ -141,20 +124,15 @@ def snapshot_download(
             `HF_HUB_DISABLE_PROGRESS_BARS` environment variable.
 
     Returns:
-        Local folder path (string) of repo snapshot
-
-    <Tip>
-
-    Raises the following errors:
-
-    - [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
-      if `token=True` and the token cannot be found.
-    - [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) if
-      ETag cannot be determined.
-    - [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
-      if some parameter value is invalid
+        `str`: folder path of the repo snapshot.
 
-    </Tip>
+    Raises:
+        - [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError)
+        if `token=True` and the token cannot be found.
+        - [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) if
+        ETag cannot be determined.
+        - [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
+        if some parameter value is invalid
     """
     if cache_dir is None:
         cache_dir = HF_HUB_CACHE