huggingface-hub 0.31.4__py3-none-any.whl → 0.32.0rc0__py3-none-any.whl

huggingface_hub/_upload_large_folder.py

@@ -42,8 +42,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 WAITING_TIME_IF_NO_TASKS = 10  # seconds
-MAX_NB_REGULAR_FILES_PER_COMMIT = 75
-MAX_NB_LFS_FILES_PER_COMMIT = 150
+MAX_NB_FILES_FETCH_UPLOAD_MODE = 100
 COMMIT_SIZE_SCALE: List[int] = [20, 50, 75, 100, 125, 200, 250, 400, 600, 1000]
 
 
@@ -404,19 +403,19 @@ def _determine_next_job(status: LargeUploadStatus) -> Optional[Tuple[WorkerJob,
         ):
             status.nb_workers_commit += 1
             logger.debug("Job: commit (more than 5 minutes since last commit attempt)")
-            return (WorkerJob.COMMIT, _get_items_to_commit(status.queue_commit))
+            return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk()))
 
         # 2. Commit if at least 100 files are ready to commit
         elif status.nb_workers_commit == 0 and status.queue_commit.qsize() >= 150:
             status.nb_workers_commit += 1
             logger.debug("Job: commit (>100 files ready)")
-            return (WorkerJob.COMMIT, _get_items_to_commit(status.queue_commit))
+            return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk()))
 
-        # 3. Get upload mode if at least 10 files
-        elif status.queue_get_upload_mode.qsize() >= 10:
+        # 3. Get upload mode if at least 100 files
+        elif status.queue_get_upload_mode.qsize() >= MAX_NB_FILES_FETCH_UPLOAD_MODE:
             status.nb_workers_get_upload_mode += 1
-            logger.debug("Job: get upload mode (>10 files ready)")
-            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, status.target_chunk()))
+            logger.debug(f"Job: get upload mode (>{MAX_NB_FILES_FETCH_UPLOAD_MODE} files ready)")
+            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE))
 
         # 4. Preupload LFS file if at least 1 file and no worker is preuploading LFS
         elif status.queue_preupload_lfs.qsize() > 0 and status.nb_workers_preupload_lfs == 0:
@@ -434,7 +433,7 @@ def _determine_next_job(status: LargeUploadStatus) -> Optional[Tuple[WorkerJob,
         elif status.queue_get_upload_mode.qsize() > 0 and status.nb_workers_get_upload_mode == 0:
             status.nb_workers_get_upload_mode += 1
             logger.debug("Job: get upload mode (no other worker getting upload mode)")
-            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, status.target_chunk()))
+            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE))
 
         # 7. Preupload LFS file if at least 1 file
         #    Skip if hf_transfer is enabled and there is already a worker preuploading LFS
@@ -455,7 +454,7 @@ def _determine_next_job(status: LargeUploadStatus) -> Optional[Tuple[WorkerJob,
         elif status.queue_get_upload_mode.qsize() > 0:
             status.nb_workers_get_upload_mode += 1
             logger.debug("Job: get upload mode")
-            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, status.target_chunk()))
+            return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE))
 
         # 10. Commit if at least 1 file and 1 min since last commit attempt
         elif (
@@ -466,7 +465,7 @@ def _determine_next_job(status: LargeUploadStatus) -> Optional[Tuple[WorkerJob,
         ):
             status.nb_workers_commit += 1
             logger.debug("Job: commit (1 min since last commit attempt)")
-            return (WorkerJob.COMMIT, _get_items_to_commit(status.queue_commit))
+            return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk()))
 
         # 11. Commit if at least 1 file all other queues are empty and all workers are waiting
         #     e.g. when it's the last commit
@@ -482,7 +481,7 @@ def _determine_next_job(status: LargeUploadStatus) -> Optional[Tuple[WorkerJob,
         ):
             status.nb_workers_commit += 1
             logger.debug("Job: commit")
-            return (WorkerJob.COMMIT, _get_items_to_commit(status.queue_commit))
+            return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk()))
 
         # 12. If all queues are empty, exit
         elif all(metadata.is_committed or metadata.should_ignore for _, metadata in status.items):
@@ -522,11 +521,13 @@ def _get_upload_mode(items: List[JOB_ITEM_T], api: "HfApi", repo_id: str, repo_t
         repo_id=repo_id,
         headers=api._build_hf_headers(),
         revision=quote(revision, safe=""),
+        endpoint=api.endpoint,
     )
     for item, addition in zip(items, additions):
         paths, metadata = item
         metadata.upload_mode = addition._upload_mode
         metadata.should_ignore = addition._should_ignore
+        metadata.remote_oid = addition._remote_oid
         metadata.save(paths)
 
 
@@ -579,6 +580,9 @@ def _build_hacky_operation(item: JOB_ITEM_T) -> HackyCommitOperationAdd:
     if metadata.sha256 is None:
         raise ValueError("sha256 must have been computed by now!")
     operation.upload_info = UploadInfo(sha256=bytes.fromhex(metadata.sha256), size=metadata.size, sample=sample)
+    operation._upload_mode = metadata.upload_mode  # type: ignore[assignment]
+    operation._should_ignore = metadata.should_ignore
+    operation._remote_oid = metadata.remote_oid
     return operation
 
 
@@ -595,30 +599,6 @@ def _get_n(queue: "queue.Queue[JOB_ITEM_T]", n: int) -> List[JOB_ITEM_T]:
     return [queue.get() for _ in range(min(queue.qsize(), n))]
 
 
-def _get_items_to_commit(queue: "queue.Queue[JOB_ITEM_T]") -> List[JOB_ITEM_T]:
-    """Special case for commit job: the number of items to commit depends on the type of files."""
-    # Can take at most 50 regular files and/or 100 LFS files in a single commit
-    items: List[JOB_ITEM_T] = []
-    nb_lfs, nb_regular = 0, 0
-    while True:
-        # If empty queue => commit everything
-        if queue.qsize() == 0:
-            return items
-
-        # If we have enough items => commit them
-        if nb_lfs >= MAX_NB_LFS_FILES_PER_COMMIT or nb_regular >= MAX_NB_REGULAR_FILES_PER_COMMIT:
-            return items
-
-        # Else, get a new item and increase counter
-        item = queue.get()
-        items.append(item)
-        _, metadata = item
-        if metadata.upload_mode == "lfs":
-            nb_lfs += 1
-        else:
-            nb_regular += 1
-
-
 def _print_overwrite(report: str) -> None:
     """Print a report, overwriting the previous lines.
 

huggingface_hub/commands/huggingface_cli.py

@@ -18,6 +18,7 @@ from huggingface_hub.commands.delete_cache import DeleteCacheCommand
 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.repo import RepoCommands
 from huggingface_hub.commands.repo_files import RepoFilesCommand
 from huggingface_hub.commands.scan_cache import ScanCacheCommand
 from huggingface_hub.commands.tag import TagCommands
@@ -37,6 +38,7 @@ def main():
     RepoFilesCommand.register_subcommand(commands_parser)
     EnvironmentCommand.register_subcommand(commands_parser)
     UserCommands.register_subcommand(commands_parser)
+    RepoCommands.register_subcommand(commands_parser)
     LfsCommands.register_subcommand(commands_parser)
     ScanCacheCommand.register_subcommand(commands_parser)
     DeleteCacheCommand.register_subcommand(commands_parser)

huggingface_hub/commands/repo.py

@@ -0,0 +1,147 @@
+# Copyright 2025 The HuggingFace Team. All rights reserved.
+#
+# 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 interact with repositories on the Hugging Face Hub.
+
+Usage:
+    # create a new dataset repo on the Hub
+    huggingface-cli repo create my-cool-dataset --repo-type=dataset
+
+    # create a private model repo on the Hub
+    huggingface-cli repo create my-cool-model --private
+"""
+
+import argparse
+from argparse import _SubParsersAction
+from typing import Optional
+
+from huggingface_hub.commands import BaseHuggingfaceCLICommand
+from huggingface_hub.commands._cli_utils import ANSI
+from huggingface_hub.constants import SPACES_SDK_TYPES
+from huggingface_hub.hf_api import HfApi
+from huggingface_hub.utils import logging
+
+
+logger = logging.get_logger(__name__)
+
+
+class RepoCommands(BaseHuggingfaceCLICommand):
+    @staticmethod
+    def register_subcommand(parser: _SubParsersAction):
+        repo_parser = parser.add_parser("repo", help="{create} Commands to interact with your huggingface.co repos.")
+        repo_subparsers = repo_parser.add_subparsers(help="huggingface.co repos related commands")
+        repo_create_parser = repo_subparsers.add_parser("create", help="Create a new repo on huggingface.co")
+        repo_create_parser.add_argument(
+            "repo_id",
+            type=str,
+            help="The ID of the repo to create to (e.g. `username/repo-name`). The username is optional and will be set to your username if not provided.",
+        )
+        repo_create_parser.add_argument(
+            "--repo-type",
+            type=str,
+            help='Optional: set to "dataset" or "space" if creating a dataset or space, default is model.',
+        )
+        repo_create_parser.add_argument(
+            "--space_sdk",
+            type=str,
+            help='Optional: Hugging Face Spaces SDK type. Required when --type is set to "space".',
+            choices=SPACES_SDK_TYPES,
+        )
+        repo_create_parser.add_argument(
+            "--private",
+            action="store_true",
+            help="Whether to create a private repository. Defaults to public unless the organization's default is private.",
+        )
+        repo_create_parser.add_argument(
+            "--token",
+            type=str,
+            help="Hugging Face token. Will default to the locally saved token if not provided.",
+        )
+        repo_create_parser.add_argument(
+            "--exist-ok",
+            action="store_true",
+            help="Do not raise an error if repo already exists.",
+        )
+        repo_create_parser.add_argument(
+            "--resource-group-id",
+            type=str,
+            help="Resource group in which to create the repo. Resource groups is only available for Enterprise Hub organizations.",
+        )
+        repo_create_parser.add_argument(
+            "--type",
+            type=str,
+            help="[Deprecated]: use --repo-type instead.",
+        )
+        repo_create_parser.add_argument(
+            "-y",
+            "--yes",
+            action="store_true",
+            help="[Deprecated] no effect.",
+        )
+        repo_create_parser.add_argument(
+            "--organization", type=str, help="[Deprecated] Pass the organization namespace directly in the repo_id."
+        )
+        repo_create_parser.set_defaults(func=lambda args: RepoCreateCommand(args))
+
+
+class RepoCreateCommand:
+    def __init__(self, args: argparse.Namespace):
+        self.repo_id: str = args.repo_id
+        self.repo_type: Optional[str] = args.repo_type or args.type
+        self.space_sdk: Optional[str] = args.space_sdk
+        self.organization: Optional[str] = args.organization
+        self.yes: bool = args.yes
+        self.private: bool = args.private
+        self.token: Optional[str] = args.token
+        self.exist_ok: bool = args.exist_ok
+        self.resource_group_id: Optional[str] = args.resource_group_id
+
+        if args.type is not None:
+            print(
+                ANSI.yellow(
+                    "The --type argument is deprecated and will be removed in a future version. Use --repo-type instead."
+                )
+            )
+        if self.organization is not None:
+            print(
+                ANSI.yellow(
+                    "The --organization argument is deprecated and will be removed in a future version. Pass the organization namespace directly in the repo_id."
+                )
+            )
+        if self.yes:
+            print(
+                ANSI.yellow(
+                    "The --yes argument is deprecated and will be removed in a future version. It does not have any effect."
+                )
+            )
+
+        self._api = HfApi()
+
+    def run(self):
+        if self.organization is not None:
+            if "/" in self.repo_id:
+                print(ANSI.red("You cannot pass both --organization and a repo_id with a namespace."))
+                exit(1)
+            self.repo_id = f"{self.organization}/{self.repo_id}"
+
+        repo_url = self._api.create_repo(
+            repo_id=self.repo_id,
+            repo_type=self.repo_type,
+            private=self.private,
+            token=self.token,
+            exist_ok=self.exist_ok,
+            resource_group_id=self.resource_group_id,
+            space_sdk=self.space_sdk,
+        )
+        print(f"Successfully created {ANSI.bold(repo_url.repo_id)} on the Hub.")
+        print(f"Your repo is now available at {ANSI.bold(repo_url)}")

huggingface_hub/commands/user.py

@@ -28,32 +28,18 @@ Usage:
 
     # find out which huggingface.co account you are logged in as
     huggingface-cli whoami
-
-    # create a new dataset repo on the Hub
-    huggingface-cli repo create mydataset --type=dataset
-
 """
 
-import subprocess
 from argparse import _SubParsersAction
 from typing import List, Optional
 
 from requests.exceptions import HTTPError
 
 from huggingface_hub.commands import BaseHuggingfaceCLICommand
-from huggingface_hub.constants import ENDPOINT, REPO_TYPES, REPO_TYPES_URL_PREFIXES, SPACES_SDK_TYPES
+from huggingface_hub.constants import ENDPOINT
 from huggingface_hub.hf_api import HfApi
 
-from .._login import (  # noqa: F401 # for backward compatibility  # noqa: F401 # for backward compatibility
-    NOTEBOOK_LOGIN_PASSWORD_HTML,
-    NOTEBOOK_LOGIN_TOKEN_HTML_END,
-    NOTEBOOK_LOGIN_TOKEN_HTML_START,
-    auth_list,
-    auth_switch,
-    login,
-    logout,
-    notebook_login,
-)
+from .._login import auth_list, auth_switch, login, logout
 from ..utils import get_stored_tokens, get_token, logging
 from ._cli_utils import ANSI
 
@@ -111,34 +97,6 @@ class UserCommands(BaseHuggingfaceCLICommand):
         auth_switch_parser.set_defaults(func=lambda args: AuthSwitchCommand(args))
         auth_list_parser = auth_subparsers.add_parser("list", help="List all stored access tokens")
         auth_list_parser.set_defaults(func=lambda args: AuthListCommand(args))
-        # new system: git-based repo system
-        repo_parser = parser.add_parser("repo", help="{create} Commands to interact with your huggingface.co repos.")
-        repo_subparsers = repo_parser.add_subparsers(help="huggingface.co repos related commands")
-        repo_create_parser = repo_subparsers.add_parser("create", help="Create a new repo on huggingface.co")
-        repo_create_parser.add_argument(
-            "name",
-            type=str,
-            help="Name for your repo. Will be namespaced under your username to build the repo id.",
-        )
-        repo_create_parser.add_argument(
-            "--type",
-            type=str,
-            help='Optional: repo_type: set to "dataset" or "space" if creating a dataset or space, default is model.',
-        )
-        repo_create_parser.add_argument("--organization", type=str, help="Optional: organization namespace.")
-        repo_create_parser.add_argument(
-            "--space_sdk",
-            type=str,
-            help='Optional: Hugging Face Spaces SDK type. Required when --type is set to "space".',
-            choices=SPACES_SDK_TYPES,
-        )
-        repo_create_parser.add_argument(
-            "-y",
-            "--yes",
-            action="store_true",
-            help="Optional: answer Yes to the prompt",
-        )
-        repo_create_parser.set_defaults(func=lambda args: RepoCreateCommand(args))
 
 
 class BaseUserCommand:
@@ -238,67 +196,3 @@ class WhoamiCommand(BaseUserCommand):
             print(e)
             print(ANSI.red(e.response.text))
             exit(1)
-
-
-class RepoCreateCommand(BaseUserCommand):
-    def run(self):
-        token = get_token()
-        if token is None:
-            print("Not logged in")
-            exit(1)
-        try:
-            stdout = subprocess.check_output(["git", "--version"]).decode("utf-8")
-            print(ANSI.gray(stdout.strip()))
-        except FileNotFoundError:
-            print("Looks like you do not have git installed, please install.")
-
-        try:
-            stdout = subprocess.check_output(["git-lfs", "--version"]).decode("utf-8")
-            print(ANSI.gray(stdout.strip()))
-        except FileNotFoundError:
-            print(
-                ANSI.red(
-                    "Looks like you do not have git-lfs installed, please install."
-                    " You can install from https://git-lfs.github.com/."
-                    " Then run `git lfs install` (you only have to do this once)."
-                )
-            )
-        print("")
-
-        user = self._api.whoami(token)["name"]
-        namespace = self.args.organization if self.args.organization is not None else user
-
-        repo_id = f"{namespace}/{self.args.name}"
-
-        if self.args.type not in REPO_TYPES:
-            print("Invalid repo --type")
-            exit(1)
-
-        if self.args.type in REPO_TYPES_URL_PREFIXES:
-            prefixed_repo_id = REPO_TYPES_URL_PREFIXES[self.args.type] + repo_id
-        else:
-            prefixed_repo_id = repo_id
-
-        print(f"You are about to create {ANSI.bold(prefixed_repo_id)}")
-
-        if not self.args.yes:
-            choice = input("Proceed? [Y/n] ").lower()
-            if not (choice == "" or choice == "y" or choice == "yes"):
-                print("Abort")
-                exit()
-        try:
-            url = self._api.create_repo(
-                repo_id=repo_id,
-                token=token,
-                repo_type=self.args.type,
-                space_sdk=self.args.space_sdk,
-            )
-        except HTTPError as e:
-            print(e)
-            print(ANSI.red(e.response.text))
-            exit(1)
-        print("\nYour repo now lives at:")
-        print(f"  {ANSI.bold(url)}")
-        print("\nYou can clone it locally with the command below, and commit/push as usual.")
-        print(f"\n  git clone {url}")
-        print("")

huggingface_hub/constants.py

@@ -271,9 +271,17 @@ ALL_INFERENCE_API_FRAMEWORKS = MAIN_INFERENCE_API_FRAMEWORKS + [
     "timm",
 ]
 
-# Xet constants
+# If OAuth didn't work after 2 redirects, there's likely a third-party cookie issue in the Space iframe view.
+# In this case, we redirect the user to the non-iframe view.
+OAUTH_MAX_REDIRECTS = 2
 
+# OAuth-related environment variables injected by the Space
+OAUTH_CLIENT_ID = os.environ.get("OAUTH_CLIENT_ID")
+OAUTH_CLIENT_SECRET = os.environ.get("OAUTH_CLIENT_SECRET")
+OAUTH_SCOPES = os.environ.get("OAUTH_SCOPES")
+OPENID_PROVIDER_URL = os.environ.get("OPENID_PROVIDER_URL")
 
+# Xet constants
 HUGGINGFACE_HEADER_X_XET_ENDPOINT = "X-Xet-Cas-Url"
 HUGGINGFACE_HEADER_X_XET_ACCESS_TOKEN = "X-Xet-Access-Token"
 HUGGINGFACE_HEADER_X_XET_EXPIRATION = "X-Xet-Token-Expiration"

huggingface_hub/dataclasses.py

@@ -269,8 +269,8 @@ def validated_field(
         metadata = {}
     metadata["validator"] = validator
     return field(  # type: ignore
-        default=default,
-        default_factory=default_factory,
+        default=default,  # type: ignore [arg-type]
+        default_factory=default_factory,  # type: ignore [arg-type]
         init=init,
         repr=repr,
         hash=hash,

huggingface_hub/file_download.py

@@ -1130,16 +1130,6 @@ def _hf_hub_download_to_cache_dir(
     # In that case store a ref.
     _cache_commit_hash_for_specific_revision(storage_folder, revision, commit_hash)
 
-    # If file already exists, return it (except if force_download=True)
-    if not force_download:
-        if os.path.exists(pointer_path):
-            return pointer_path
-
-        if os.path.exists(blob_path):
-            # we have the blob already, but not the pointer
-            _create_symlink(blob_path, pointer_path, new_blob=False)
-            return pointer_path
-
     # Prevent parallel downloads of the same file with a lock.
     # etag could be duplicated across repos,
     lock_path = os.path.join(locks_dir, repo_folder_name(repo_id=repo_id, repo_type=repo_type), f"{etag}.lock")
@@ -1152,9 +1142,21 @@ def _hf_hub_download_to_cache_dir(
     if os.name == "nt" and len(os.path.abspath(blob_path)) > 255:
         blob_path = "\\\\?\\" + os.path.abspath(blob_path)
 
+    Path(lock_path).parent.mkdir(parents=True, exist_ok=True)
+
+    # pointer already exists -> immediate return
+    if not force_download and os.path.exists(pointer_path):
+        return pointer_path
+
+    # Blob exists but pointer must be (safely) created -> take the lock
+    if not force_download and os.path.exists(blob_path):
+        with WeakFileLock(lock_path):
+            if not os.path.exists(pointer_path):
+                _create_symlink(blob_path, pointer_path, new_blob=False)
+            return pointer_path
+
     # Local file doesn't exist or etag isn't a match => retrieve file from remote (or cache)
 
-    Path(lock_path).parent.mkdir(parents=True, exist_ok=True)
     with WeakFileLock(lock_path):
         _download_to_tmp_and_move(
             incomplete_path=Path(blob_path + ".incomplete"),

huggingface_hub/hf_api.py

@@ -3623,7 +3623,7 @@ class HfApi:
             exist_ok (`bool`, *optional*, defaults to `False`):
                 If `True`, do not raise an error if repo already exists.
             resource_group_id (`str`, *optional*):
-                Resource group in which to create the repo. Resource groups is only available for organizations and
+                Resource group in which to create the repo. Resource groups is only available for Enterprise Hub organizations and
                 allow to define which members of the organization can access the resource. The ID of a resource group
                 can be found in the URL of the resource's page on the Hub (e.g. `"66670e5163145ca562cb1988"`).
                 To learn more about resource groups, see https://huggingface.co/docs/hub/en/security-resource-groups.
@@ -4421,20 +4421,23 @@ class HfApi:
         new_additions = [addition for addition in additions if not addition._is_uploaded]
 
         # Check which new files are LFS
-        try:
-            _fetch_upload_modes(
-                additions=new_additions,
-                repo_type=repo_type,
-                repo_id=repo_id,
-                headers=headers,
-                revision=revision,
-                endpoint=self.endpoint,
-                create_pr=create_pr or False,
-                gitignore_content=gitignore_content,
-            )
-        except RepositoryNotFoundError as e:
-            e.append_to_message(_CREATE_COMMIT_NO_REPO_ERROR_MESSAGE)
-            raise
+        # For some items, we might have already fetched the upload mode (in case of upload_large_folder)
+        additions_no_upload_mode = [addition for addition in new_additions if addition._upload_mode is None]
+        if len(additions_no_upload_mode) > 0:
+            try:
+                _fetch_upload_modes(
+                    additions=additions_no_upload_mode,
+                    repo_type=repo_type,
+                    repo_id=repo_id,
+                    headers=headers,
+                    revision=revision,
+                    endpoint=self.endpoint,
+                    create_pr=create_pr or False,
+                    gitignore_content=gitignore_content,
+                )
+            except RepositoryNotFoundError as e:
+                e.append_to_message(_CREATE_COMMIT_NO_REPO_ERROR_MESSAGE)
+                raise
 
         # Filter out regular files
         new_lfs_additions = [addition for addition in new_additions if addition._upload_mode == "lfs"]
@@ -7566,9 +7569,9 @@ class HfApi:
         region: str,
         vendor: str,
         account_id: Optional[str] = None,
-        min_replica: int = 0,
+        min_replica: int = 1,
         max_replica: int = 1,
-        scale_to_zero_timeout: int = 15,
+        scale_to_zero_timeout: Optional[int] = None,
         revision: Optional[str] = None,
         task: Optional[str] = None,
         custom_image: Optional[Dict] = None,
@@ -7604,11 +7607,13 @@ class HfApi:
             account_id (`str`, *optional*):
                 The account ID used to link a VPC to a private Inference Endpoint (if applicable).
             min_replica (`int`, *optional*):
-                The minimum number of replicas (instances) to keep running for the Inference Endpoint. Defaults to 0.
+                The minimum number of replicas (instances) to keep running for the Inference Endpoint. To enable
+                scaling to zero, set this value to 0 and adjust `scale_to_zero_timeout` accordingly. Defaults to 1.
             max_replica (`int`, *optional*):
                 The maximum number of replicas (instances) to scale to for the Inference Endpoint. Defaults to 1.
             scale_to_zero_timeout (`int`, *optional*):
-                The duration in minutes before an inactive endpoint is scaled to zero. Defaults to 15.
+                The duration in minutes before an inactive endpoint is scaled to zero, or no scaling to zero if
+                set to None and `min_replica` is not 0. Defaults to None.
             revision (`str`, *optional*):
                 The specific model revision to deploy on the Inference Endpoint (e.g. `"6c0e6080953db56375760c0471a8c5f2929baf11"`).
             task (`str`, *optional*):
@@ -7693,8 +7698,32 @@ class HfApi:
             ...    secrets={"MY_SECRET_KEY": "secret_value"},
             ...    tags=["dev", "text-generation"],
             ... )
+            ```
 
+            ```python
+            # Start an Inference Endpoint running ProsusAI/finbert while scaling to zero in 15 minutes
+            >>> from huggingface_hub import HfApi
+            >>> api = HfApi()
+            >>> endpoint = api.create_inference_endpoint(
+            ...     "finbert-classifier",
+            ...     repository="ProsusAI/finbert",
+            ...     framework="pytorch",
+            ...     task="text-classification",
+            ...     min_replica=0,
+            ...     scale_to_zero_timeout=15,
+            ...     accelerator="cpu",
+            ...     vendor="aws",
+            ...     region="us-east-1",
+            ...     type="protected",
+            ...     instance_size="x2",
+            ...     instance_type="intel-icl",
+            ... )
+            >>> endpoint.wait(timeout=300)
+            # Run inference on the endpoint
+            >>> endpoint.client.text_generation(...)
+            TextClassificationOutputElement(label='positive', score=0.8983615040779114)
             ```
+
         """
         namespace = namespace or self._get_namespace(token=token)
 

huggingface_hub/hub_mixin.py

@@ -353,7 +353,7 @@ class ModelHubMixin:
     def _encode_arg(cls, arg: Any) -> Any:
         """Encode an argument into a JSON serializable format."""
         if is_dataclass(arg):
-            return asdict(arg)
+            return asdict(arg)  # type: ignore[arg-type]
         for type_, (encoder, _) in cls._hub_mixin_coders.items():
             if isinstance(arg, type_):
                 if arg is None:
@@ -767,7 +767,7 @@ class PyTorchModelHubMixin(ModelHubMixin):
     def _save_pretrained(self, save_directory: Path) -> None:
         """Save weights from a Pytorch model to a local directory."""
         model_to_save = self.module if hasattr(self, "module") else self  # type: ignore
-        save_model_as_safetensor(model_to_save, str(save_directory / constants.SAFETENSORS_SINGLE_FILE))
+        save_model_as_safetensor(model_to_save, str(save_directory / constants.SAFETENSORS_SINGLE_FILE))  # type: ignore [arg-type]
 
     @classmethod
     def _from_pretrained(