huggingface-hub 0.31.0rc0__py3-none-any.whl → 1.1.3__py3-none-any.whl

huggingface_hub/_jobs_api.py

@@ -0,0 +1,301 @@
+# coding=utf-8
+# Copyright 2025-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.
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional, Union
+
+from huggingface_hub import constants
+from huggingface_hub._space_api import SpaceHardware
+from huggingface_hub.utils._datetime import parse_datetime
+
+
+class JobStage(str, Enum):
+    """
+    Enumeration of possible stage of a Job on the Hub.
+
+    Value can be compared to a string:
+    ```py
+    assert JobStage.COMPLETED == "COMPLETED"
+    ```
+    Possible values are: `COMPLETED`, `CANCELED`, `ERROR`, `DELETED`, `RUNNING`.
+    Taken from https://github.com/huggingface/moon-landing/blob/main/server/job_types/JobInfo.ts#L61 (private url).
+    """
+
+    # Copied from moon-landing > server > lib > Job.ts
+    COMPLETED = "COMPLETED"
+    CANCELED = "CANCELED"
+    ERROR = "ERROR"
+    DELETED = "DELETED"
+    RUNNING = "RUNNING"
+
+
+@dataclass
+class JobStatus:
+    stage: JobStage
+    message: Optional[str]
+
+
+@dataclass
+class JobOwner:
+    id: str
+    name: str
+    type: str
+
+
+@dataclass
+class JobInfo:
+    """
+    Contains information about a Job.
+
+    Args:
+        id (`str`):
+            Job ID.
+        created_at (`datetime` or `None`):
+            When the Job was created.
+        docker_image (`str` or `None`):
+            The Docker image from Docker Hub used for the Job.
+            Can be None if space_id is present instead.
+        space_id (`str` or `None`):
+            The Docker image from Hugging Face Spaces used for the Job.
+            Can be None if docker_image is present instead.
+        command (`list[str]` or `None`):
+            Command of the Job, e.g. `["python", "-c", "print('hello world')"]`
+        arguments (`list[str]` or `None`):
+            Arguments passed to the command
+        environment (`dict[str]` or `None`):
+            Environment variables of the Job as a dictionary.
+        secrets (`dict[str]` or `None`):
+            Secret environment variables of the Job (encrypted).
+        flavor (`str` or `None`):
+            Flavor for the hardware, as in Hugging Face Spaces. See [`SpaceHardware`] for possible values.
+            E.g. `"cpu-basic"`.
+        status: (`JobStatus` or `None`):
+            Status of the Job, e.g. `JobStatus(stage="RUNNING", message=None)`
+            See [`JobStage`] for possible stage values.
+        owner: (`JobOwner` or `None`):
+            Owner of the Job, e.g. `JobOwner(id="5e9ecfc04957053f60648a3e", name="lhoestq", type="user")`
+
+    Example:
+
+    ```python
+    >>> from huggingface_hub import run_job
+    >>> job = run_job(
+    ...     image="python:3.12",
+    ...     command=["python", "-c", "print('Hello from the cloud!')"]
+    ... )
+    >>> job
+    JobInfo(id='687fb701029421ae5549d998', created_at=datetime.datetime(2025, 7, 22, 16, 6, 25, 79000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='RUNNING', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq', type='user'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687fb701029421ae5549d998')
+    >>> job.id
+    '687fb701029421ae5549d998'
+    >>> job.url
+    'https://huggingface.co/jobs/lhoestq/687fb701029421ae5549d998'
+    >>> job.status.stage
+    'RUNNING'
+    ```
+    """
+
+    id: str
+    created_at: Optional[datetime]
+    docker_image: Optional[str]
+    space_id: Optional[str]
+    command: Optional[list[str]]
+    arguments: Optional[list[str]]
+    environment: Optional[dict[str, Any]]
+    secrets: Optional[dict[str, Any]]
+    flavor: Optional[SpaceHardware]
+    status: JobStatus
+    owner: JobOwner
+
+    # Inferred fields
+    endpoint: str
+    url: str
+
+    def __init__(self, **kwargs) -> None:
+        self.id = kwargs["id"]
+        created_at = kwargs.get("createdAt") or kwargs.get("created_at")
+        self.created_at = parse_datetime(created_at) if created_at else None
+        self.docker_image = kwargs.get("dockerImage") or kwargs.get("docker_image")
+        self.space_id = kwargs.get("spaceId") or kwargs.get("space_id")
+        owner = kwargs.get("owner", {})
+        self.owner = JobOwner(id=owner["id"], name=owner["name"], type=owner["type"])
+        self.command = kwargs.get("command")
+        self.arguments = kwargs.get("arguments")
+        self.environment = kwargs.get("environment")
+        self.secrets = kwargs.get("secrets")
+        self.flavor = kwargs.get("flavor")
+        status = kwargs.get("status", {})
+        self.status = JobStatus(stage=status["stage"], message=status.get("message"))
+
+        # Inferred fields
+        self.endpoint = kwargs.get("endpoint", constants.ENDPOINT)
+        self.url = f"{self.endpoint}/jobs/{self.owner.name}/{self.id}"
+
+
+@dataclass
+class JobSpec:
+    docker_image: Optional[str]
+    space_id: Optional[str]
+    command: Optional[list[str]]
+    arguments: Optional[list[str]]
+    environment: Optional[dict[str, Any]]
+    secrets: Optional[dict[str, Any]]
+    flavor: Optional[SpaceHardware]
+    timeout: Optional[int]
+    tags: Optional[list[str]]
+    arch: Optional[str]
+
+    def __init__(self, **kwargs) -> None:
+        self.docker_image = kwargs.get("dockerImage") or kwargs.get("docker_image")
+        self.space_id = kwargs.get("spaceId") or kwargs.get("space_id")
+        self.command = kwargs.get("command")
+        self.arguments = kwargs.get("arguments")
+        self.environment = kwargs.get("environment")
+        self.secrets = kwargs.get("secrets")
+        self.flavor = kwargs.get("flavor")
+        self.timeout = kwargs.get("timeout")
+        self.tags = kwargs.get("tags")
+        self.arch = kwargs.get("arch")
+
+
+@dataclass
+class LastJobInfo:
+    id: str
+    at: datetime
+
+    def __init__(self, **kwargs) -> None:
+        self.id = kwargs["id"]
+        self.at = parse_datetime(kwargs["at"])
+
+
+@dataclass
+class ScheduledJobStatus:
+    last_job: Optional[LastJobInfo]
+    next_job_run_at: Optional[datetime]
+
+    def __init__(self, **kwargs) -> None:
+        last_job = kwargs.get("lastJob") or kwargs.get("last_job")
+        self.last_job = LastJobInfo(**last_job) if last_job else None
+        next_job_run_at = kwargs.get("nextJobRunAt") or kwargs.get("next_job_run_at")
+        self.next_job_run_at = parse_datetime(str(next_job_run_at)) if next_job_run_at else None
+
+
+@dataclass
+class ScheduledJobInfo:
+    """
+    Contains information about a Job.
+
+    Args:
+        id (`str`):
+            Scheduled Job ID.
+        created_at (`datetime` or `None`):
+            When the scheduled Job was created.
+        tags (`list[str]` or `None`):
+            The tags of the scheduled Job.
+        schedule (`str` or `None`):
+            One of "@annually", "@yearly", "@monthly", "@weekly", "@daily", "@hourly", or a
+            CRON schedule expression (e.g., '0 9 * * 1' for 9 AM every Monday).
+        suspend (`bool` or `None`):
+            Whether the scheduled job is suspended (paused).
+        concurrency (`bool` or `None`):
+            Whether multiple instances of this Job can run concurrently.
+        status (`ScheduledJobStatus` or `None`):
+            Status of the scheduled Job.
+        owner: (`JobOwner` or `None`):
+            Owner of the scheduled Job, e.g. `JobOwner(id="5e9ecfc04957053f60648a3e", name="lhoestq", type="user")`
+        job_spec: (`JobSpec` or `None`):
+            Specifications of the Job.
+
+    Example:
+
+    ```python
+    >>> from huggingface_hub import run_job
+    >>> scheduled_job = create_scheduled_job(
+    ...     image="python:3.12",
+    ...     command=["python", "-c", "print('Hello from the cloud!')"],
+    ...     schedule="@hourly",
+    ... )
+    >>> scheduled_job.id
+    '687fb701029421ae5549d999'
+    >>> scheduled_job.status.next_job_run_at
+    datetime.datetime(2025, 7, 22, 17, 6, 25, 79000, tzinfo=datetime.timezone.utc)
+    ```
+    """
+
+    id: str
+    created_at: Optional[datetime]
+    job_spec: JobSpec
+    schedule: Optional[str]
+    suspend: Optional[bool]
+    concurrency: Optional[bool]
+    status: ScheduledJobStatus
+    owner: JobOwner
+
+    def __init__(self, **kwargs) -> None:
+        self.id = kwargs["id"]
+        created_at = kwargs.get("createdAt") or kwargs.get("created_at")
+        self.created_at = parse_datetime(created_at) if created_at else None
+        self.job_spec = JobSpec(**(kwargs.get("job_spec") or kwargs.get("jobSpec", {})))
+        self.schedule = kwargs.get("schedule")
+        self.suspend = kwargs.get("suspend")
+        self.concurrency = kwargs.get("concurrency")
+        status = kwargs.get("status", {})
+        self.status = ScheduledJobStatus(
+            last_job=status.get("last_job") or status.get("lastJob"),
+            next_job_run_at=status.get("next_job_run_at") or status.get("nextJobRunAt"),
+        )
+        owner = kwargs.get("owner", {})
+        self.owner = JobOwner(id=owner["id"], name=owner["name"], type=owner["type"])
+
+
+def _create_job_spec(
+    *,
+    image: str,
+    command: list[str],
+    env: Optional[dict[str, Any]],
+    secrets: Optional[dict[str, Any]],
+    flavor: Optional[SpaceHardware],
+    timeout: Optional[Union[int, float, str]],
+) -> dict[str, Any]:
+    # prepare job spec to send to HF Jobs API
+    job_spec: dict[str, Any] = {
+        "command": command,
+        "arguments": [],
+        "environment": env or {},
+        "flavor": flavor or SpaceHardware.CPU_BASIC,
+    }
+    # secrets are optional
+    if secrets:
+        job_spec["secrets"] = secrets
+    # timeout is optional
+    if timeout:
+        time_units_factors = {"s": 1, "m": 60, "h": 3600, "d": 3600 * 24}
+        if isinstance(timeout, str) and timeout[-1] in time_units_factors:
+            job_spec["timeoutSeconds"] = int(float(timeout[:-1]) * time_units_factors[timeout[-1]])
+        else:
+            job_spec["timeoutSeconds"] = int(timeout)
+    # input is either from docker hub or from HF spaces
+    for prefix in (
+        "https://huggingface.co/spaces/",
+        "https://hf.co/spaces/",
+        "huggingface.co/spaces/",
+        "hf.co/spaces/",
+    ):
+        if image.startswith(prefix):
+            job_spec["spaceId"] = image[len(prefix) :]
+            break
+    else:
+        job_spec["dockerImage"] = image
+    return job_spec

huggingface_hub/_local_folder.py

@@ -86,7 +86,13 @@ class LocalDownloadFilePaths:
 
     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.parent / f"{_short_hash(self.metadata_path.name)}.{etag}.incomplete"
+        path = self.metadata_path.parent / f"{_short_hash(self.metadata_path.name)}.{etag}.incomplete"
+        resolved_path = str(path.resolve())
+        # Some Windows versions do not allow for paths longer than 255 characters.
+        # In this case, we must specify it as an extended path by using the "\\?\" prefix.
+        if os.name == "nt" and len(resolved_path) > 255 and not resolved_path.startswith("\\\\?\\"):
+            path = Path("\\\\?\\" + resolved_path)
+        return path
 
 
 @dataclass(frozen=True)
@@ -149,6 +155,7 @@ class LocalUploadFileMetadata:
     should_ignore: Optional[bool] = None
     sha256: Optional[str] = None
     upload_mode: Optional[str] = None
+    remote_oid: Optional[str] = None
     is_uploaded: bool = False
     is_committed: bool = False
 
@@ -174,6 +181,10 @@ class LocalUploadFileMetadata:
                     f.write(self.upload_mode)
                 f.write("\n")
 
+                if self.remote_oid is not None:
+                    f.write(self.remote_oid)
+                f.write("\n")
+
                 f.write(str(int(self.is_uploaded)) + "\n")
                 f.write(str(int(self.is_committed)) + "\n")
 
@@ -195,7 +206,7 @@ def get_local_download_paths(local_dir: Path, filename: str) -> LocalDownloadFil
         [`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
+    # 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:
@@ -235,7 +246,7 @@ def get_local_upload_paths(local_dir: Path, filename: str) -> LocalUploadFilePat
         [`LocalUploadFilePaths`]: the paths to the files (file_path, lock_path, metadata_path).
     """
     # filename is the path in the Hub repository (separated by '/')
-    # make sure to have a cross platform transcription
+    # 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:
@@ -346,6 +357,9 @@ def read_upload_metadata(local_dir: Path, filename: str) -> LocalUploadFileMetad
                     if upload_mode not in (None, "regular", "lfs"):
                         raise ValueError(f"Invalid upload mode in metadata {paths.path_in_repo}: {upload_mode}")
 
+                    _remote_oid = f.readline().strip()
+                    remote_oid = None if _remote_oid == "" else _remote_oid
+
                     is_uploaded = bool(int(f.readline().strip()))
                     is_committed = bool(int(f.readline().strip()))
 
@@ -355,6 +369,7 @@ def read_upload_metadata(local_dir: Path, filename: str) -> LocalUploadFileMetad
                         should_ignore=should_ignore,
                         sha256=sha256,
                         upload_mode=upload_mode,
+                        remote_oid=remote_oid,
                         is_uploaded=is_uploaded,
                         is_committed=is_committed,
                     )

huggingface_hub/_login.py

@@ -19,9 +19,11 @@ from getpass import getpass
 from pathlib import Path
 from typing import Optional
 
+import typer
+
 from . import constants
-from .commands._cli_utils import ANSI
 from .utils import (
+    ANSI,
     capture_output,
     get_token,
     is_google_colab,
@@ -41,7 +43,6 @@ from .utils._auth import (
     _save_token,
     get_stored_tokens,
 )
-from .utils._deprecation import _deprecate_arguments, _deprecate_positional_args
 
 
 logger = logging.get_logger(__name__)
@@ -55,18 +56,11 @@ _HF_LOGO_ASCII = """
 """
 
 
-@_deprecate_arguments(
-    version="1.0",
-    deprecated_args="write_permission",
-    custom_message="Fine-grained tokens added complexity to the permissions, making it irrelevant to check if a token has 'write' access.",
-)
-@_deprecate_positional_args(version="1.0")
 def login(
     token: Optional[str] = None,
     *,
     add_to_git_credential: bool = False,
-    new_session: bool = True,
-    write_permission: bool = False,
+    skip_if_logged_in: bool = False,
 ) -> None:
     """Login the machine to access the Hub.
 
@@ -75,24 +69,18 @@ def login(
     components. If `token` is not provided, it will be prompted to the user either with
     a widget (in a notebook) or via the terminal.
 
-    To log in from outside of a script, one can also use `huggingface-cli login` which is
+    To log in from outside of a script, one can also use `hf auth login` which is
     a cli command that wraps [`login`].
 
-    <Tip>
-
-    [`login`] is a drop-in replacement method for [`notebook_login`] as it wraps and
-    extends its capabilities.
-
-    </Tip>
-
-    <Tip>
+    > [!TIP]
+    > [`login`] is a drop-in replacement method for [`notebook_login`] as it wraps and
+    > extends its capabilities.
 
-    When the token is not passed, [`login`] will automatically detect if the script runs
-    in a notebook or not. However, this detection might not be accurate due to the
-    variety of notebooks that exists nowadays. If that is the case, you can always force
-    the UI by using [`notebook_login`] or [`interpreter_login`].
-
-    </Tip>
+    > [!TIP]
+    > When the token is not passed, [`login`] will automatically detect if the script runs
+    > in a notebook or not. However, this detection might not be accurate due to the
+    > variety of notebooks that exists nowadays. If that is the case, you can always force
+    > the UI by using [`notebook_login`] or [`interpreter_login`].
 
     Args:
         token (`str`, *optional*):
@@ -102,10 +90,8 @@ def login(
             is configured, a warning will be displayed to the user. If `token` is `None`,
             the value of `add_to_git_credential` is ignored and will be prompted again
             to the end user.
-        new_session (`bool`, defaults to `True`):
-            If `True`, will request a token even if one is already saved on the machine.
-        write_permission (`bool`):
-            Ignored and deprecated argument.
+        skip_if_logged_in (`bool`, defaults to `False`):
+            If `True`, do not prompt for token if user is already logged in.
     Raises:
         [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError)
             If an organization token is passed. Only personal account tokens are valid
@@ -120,14 +106,14 @@ def login(
             logger.info(
                 "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 "
+                "`--add-to-git-credential` if using via `hf`CLI if "
                 "you want to set the git credential as well."
             )
         _login(token, add_to_git_credential=add_to_git_credential)
     elif is_notebook():
-        notebook_login(new_session=new_session)
+        notebook_login(skip_if_logged_in=skip_if_logged_in)
     else:
-        interpreter_login(new_session=new_session)
+        interpreter_login(skip_if_logged_in=skip_if_logged_in)
 
 
 def logout(token_name: Optional[str] = None) -> None:
@@ -137,7 +123,7 @@ def logout(token_name: Optional[str] = None) -> None:
 
     Args:
         token_name (`str`, *optional*):
-            Name of the access token to logout from. If `None`, will logout from all saved access tokens.
+            Name of the access token to logout from. If `None`, will log out from all saved access tokens.
     Raises:
         [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError):
             If the access token name is not found.
@@ -233,7 +219,7 @@ def auth_list() -> None:
         )
     elif current_token_name is None:
         logger.warning(
-            "\nNote: No active token is set and no environment variable `HF_TOKEN` is found. Use `huggingface-cli login` to log in."
+            "\nNote: No active token is set and no environment variable `HF_TOKEN` is found. Use `hf auth login` to log in."
         )
 
 
@@ -242,13 +228,7 @@ def auth_list() -> None:
 ###
 
 
-@_deprecate_arguments(
-    version="1.0",
-    deprecated_args="write_permission",
-    custom_message="Fine-grained tokens added complexity to the permissions, making it irrelevant to check if a token has 'write' access.",
-)
-@_deprecate_positional_args(version="1.0")
-def interpreter_login(*, new_session: bool = True, write_permission: bool = False) -> None:
+def interpreter_login(*, skip_if_logged_in: bool = False) -> None:
     """
     Displays a prompt to log in to the HF website and store the token.
 
@@ -259,22 +239,18 @@ def interpreter_login(*, new_session: bool = True, write_permission: bool = Fals
     For more details, see [`login`].
 
     Args:
-        new_session (`bool`, defaults to `True`):
-            If `True`, will request a token even if one is already saved on the machine.
-        write_permission (`bool`):
-            Ignored and deprecated argument.
+        skip_if_logged_in (`bool`, defaults to `False`):
+            If `True`, do not prompt for token if user is already logged in.
     """
-    if not new_session and get_token() is not None:
+    if not skip_if_logged_in and get_token() is not None:
         logger.info("User is already logged in.")
         return
 
-    from .commands.delete_cache import _ask_for_confirmation_no_tui
-
     print(_HF_LOGO_ASCII)
     if get_token() is not None:
         logger.info(
-            "    A token is already saved on your machine. Run `huggingface-cli"
-            " whoami` to get more information or `huggingface-cli logout` if you want"
+            "    A token is already saved on your machine. Run `hf auth whoami`"
+            " to get more information or `hf auth logout` if you want"
             " to log out."
         )
         logger.info("    Setting a new token will erase the existing one.")
@@ -285,7 +261,7 @@ def interpreter_login(*, new_session: bool = True, write_permission: bool = Fals
     if os.name == "nt":
         logger.info("Token can be pasted using 'Right-Click'.")
     token = getpass("Enter your token (input will not be visible): ")
-    add_to_git_credential = _ask_for_confirmation_no_tui("Add token as git credential?")
+    add_to_git_credential = typer.confirm("Add token as git credential?")
 
     _login(token=token, add_to_git_credential=add_to_git_credential)
 
@@ -314,13 +290,7 @@ NOTEBOOK_LOGIN_TOKEN_HTML_END = """
 notebooks. </center>"""
 
 
-@_deprecate_arguments(
-    version="1.0",
-    deprecated_args="write_permission",
-    custom_message="Fine-grained tokens added complexity to the permissions, making it irrelevant to check if a token has 'write' access.",
-)
-@_deprecate_positional_args(version="1.0")
-def notebook_login(*, new_session: bool = True, write_permission: bool = False) -> None:
+def notebook_login(*, skip_if_logged_in: bool = False) -> None:
     """
     Displays a widget to log in to the HF website and store the token.
 
@@ -331,10 +301,8 @@ def notebook_login(*, new_session: bool = True, write_permission: bool = False)
     For more details, see [`login`].
 
     Args:
-        new_session (`bool`, defaults to `True`):
-            If `True`, will request a token even if one is already saved on the machine.
-        write_permission (`bool`):
-            Ignored and deprecated argument.
+        skip_if_logged_in (`bool`, defaults to `False`):
+            If `True`, do not prompt for token if user is already logged in.
     """
     try:
         import ipywidgets.widgets as widgets  # type: ignore
@@ -344,7 +312,7 @@ def notebook_login(*, new_session: bool = True, write_permission: bool = False)
             "The `notebook_login` function can only be used in a notebook (Jupyter or"
             " Colab) and you need the `ipywidgets` module: `pip install ipywidgets`."
         )
-    if not new_session and get_token() is not None:
+    if not skip_if_logged_in and get_token() is not None:
         logger.info("User is already logged in.")
         return