Return the current level for the HuggingFace Hub’s root logger.

Sets the level for the HuggingFace Hub’s root logger.

Sets the verbosity to logging.INFO.

Sets the verbosity to logging.DEBUG.

Sets the verbosity to logging.WARNING.

Sets the verbosity to logging.ERROR.

Disable propagation of the library log outputs. Note that log propagation is disabled by default.

Enable propagation of the library log outputs. Please disable the HuggingFace Hub’s default handler to prevent double logging if the root logger has been configured.

Returns a logger with the specified name. This function is not supposed to be directly accessed by library users.

>>> from huggingface_hub import get_logger

>>> logger = get_logger(__file__)
>>> logger.set_verbosity_info()

Return whether progress bars are globally disabled or not.

Progress bars used in huggingface_hub can be enable or disabled globally using enable_progress_bars() and disable_progress_bars() or by setting HF_HUB_DISABLE_PROGRESS_BARS as environment variable.

Disable globally progress bars used in huggingface_hub except if HF_HUB_DISABLE_PROGRESS_BARS environment variable has been set.

Use enable_progress_bars() to re-enable them.

Enable globally progress bars used in huggingface_hub except if HF_HUB_DISABLE_PROGRESS_BARS environment variable has been set.

Use disable_progress_bars() to disable them.

Configure the HTTP backend by providing a backend_factory. Any HTTP calls made by huggingface_hub will use a Session object instantiated by this factory. This can be useful if you are running your scripts in a specific environment requiring custom configuration (e.g. custom proxy or certifications).

Use get_session() to get a configured Session. Since requests.Session is not guaranteed to be thread-safe, huggingface_hub creates 1 Session instance per thread. They are all instantiated using the same backend_factory set in configure_http_backend(). A LRU cache is used to cache the created sessions (and connections) between calls. Max size is 128 to avoid memory leaks if thousands of threads are spawned.

See this issue to know more about thread-safety in requests.

import requests
from huggingface_hub import configure_http_backend, get_session

# Create a factory function that returns a Session with configured proxies
def backend_factory() -> requests.Session:
    session = requests.Session()
    session.proxies = {"http": "http://10.10.1.10:3128", "https": "https://10.10.1.11:1080"}
    return session

# Set it as the default session factory
configure_http_backend(backend_factory=backend_factory)

# In practice, this is mostly done internally in `huggingface_hub`
session = get_session()

Get a requests.Session object, using the session factory from the user.

Use get_session() to get a configured Session. Since requests.Session is not guaranteed to be thread-safe, huggingface_hub creates 1 Session instance per thread. They are all instantiated using the same backend_factory set in configure_http_backend(). A LRU cache is used to cache the created sessions (and connections) between calls. Max size is 128 to avoid memory leaks if thousands of threads are spawned.

See this issue to know more about thread-safety in requests.

import requests
from huggingface_hub import configure_http_backend, get_session

# Create a factory function that returns a Session with configured proxies
def backend_factory() -> requests.Session:
    session = requests.Session()
    session.proxies = {"http": "http://10.10.1.10:3128", "https": "https://10.10.1.11:1080"}
    return session

# Set it as the default session factory
configure_http_backend(backend_factory=backend_factory)

# In practice, this is mostly done internally in `huggingface_hub`
session = get_session()

Internal version of response.raise_for_status() that will refine a potential HTTPError. Raised exception will be an instance of HfHubHTTPError.

This helper is meant to be the unique method to raise_for_status when making a call to the Hugging Face Hub.

    import requests
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

HTTPError to inherit from for any custom HTTP Error raised in HF Hub.

Any HTTPError is converted at least into a HfHubHTTPError. If some information is sent back by the server, it will be added to the error message.

Added details:

• Request id from “X-Request-Id” header if exists.
• Server error message from the header “X-Error-Message”.
• Server error message if we can found one in the response body.

    import requests
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

Raised when trying to access a hf.co URL with an invalid repository name, or with a private repo name the user does not have access to.

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.utils._errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated.
Invalid username or password.

Raised when trying to access a gated repository for which the user is not on the authorized list.

Note: derives from RepositoryNotFoundError to ensure backward compatibility.

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.utils._errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

Raised when trying to access a hf.co URL with a valid repository but an invalid revision.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.utils._errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

Raised when trying to access a hf.co URL with a valid repository and revision but an invalid filename.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.utils._errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

Raised by hf_raise_for_status when the server returns a HTTP 400 error.

>>> resp = requests.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.utils._errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

Raised when trying to access a file or snapshot that is not on the disk when network is disabled or unavailable (connection issue). The entry may exist on the Hub.

Note: ValueError type is to ensure backward compatibility. Note: LocalEntryNotFoundError derives from HTTPError because of EntryNotFoundError even when it is not a network issue.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.utils._errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

Raised when a request is made but HF_HUB_OFFLINE=1 is set as environment variable.

Sends telemetry that helps tracking usage of different HF libraries.

This usage data helps us debug issues and prioritize new features. However, we understand that not everyone wants to share additional information, and we respect your privacy. You can disable telemetry collection by setting the HF_HUB_DISABLE_TELEMETRY=1 as environment variable. Telemetry is also disabled in offline mode (i.e. when setting HF_HUB_OFFLINE=1).

Telemetry collection is run in a separate thread to minimize impact for the user.

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

Validate values received as argument for any public method of huggingface_hub.

The goal of this decorator is to harmonize validation of arguments reused everywhere. By default, all defined validators are tested.

Validators:

• validate_repo_id(): repo_id must be "repo_name" or "namespace/repo_name". Namespace is a username or an organization.
• smoothly_deprecate_use_auth_token(): Use token instead of use_auth_token (only if use_auth_token is not expected by the decorated function - in practice, always the case in huggingface_hub).

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> @validate_hf_hub_args
... def my_cool_auth_method(token: str):
...     print(token)

>>> my_cool_auth_method(token="a token")
"a token"

>>> my_cool_auth_method(use_auth_token="a use_auth_token")
"a use_auth_token"

>>> my_cool_auth_method(token="a token", use_auth_token="a use_auth_token")
UserWarning: Both `token` and `use_auth_token` are passed (...)
"a token"

Generic exception thrown by huggingface_hub validators.

Inherits from ValueError.

Validate repo_id is valid.

This is not meant to replace the proper validation made on the Hub but rather to avoid local inconsistencies whenever possible (example: passing repo_type in the repo_id is forbidden).

Rules:

• Between 1 and 96 characters.
• Either “repo_name” or “namespace/repo_name”
• [a-zA-Z0-9] or ”-”, ”_”, ”.”
• ”—” and ”..” are forbidden

Valid: "foo", "foo/bar", "123", "Foo-BAR_foo.bar123"

Not valid: "datasets/foo/bar", ".repo_id", "foo--bar", "foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Discussed in https://github.com/huggingface/huggingface_hub/issues/1008. In moon-landing (internal repository):

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

Smoothly deprecate use_auth_token in the huggingface_hub codebase.

The long-term goal is to remove any mention of use_auth_token in the codebase in favor of a unique and less verbose token argument. This will be done a few steps:

0. Step 0: methods that require a read-access to the Hub use the use_auth_token argument (str, bool or None). Methods requiring write-access have a token argument (str, None). This implicit rule exists to be able to not send the token when not necessary (use_auth_token=False) even if logged in.

1. Step 1: we want to harmonize everything and use token everywhere (supporting token=False for read-only methods). In order not to break existing code, if use_auth_token is passed to a function, the use_auth_token value is passed as token instead, without any warning. a. Corner case: if both use_auth_token and token values are passed, a warning is thrown and the use_auth_token value is ignored.

2. Step 2: Once it is release, we should push downstream libraries to switch from use_auth_token to token as much as possible, but without throwing a warning (e.g. manually create issues on the corresponding repos).

3. Step 3: After a transitional period (6 months e.g. until April 2023?), we update huggingface_hub to throw a warning on use_auth_token. Hopefully, very few users will be impacted as it would have already been fixed. In addition, unit tests in huggingface_hub must be adapted to expect warnings to be thrown (but still use use_auth_token as before).

4. Step 4: After a normal deprecation cycle (3 releases ?), remove this validator. use_auth_token will definitely not be supported. In addition, we update unit tests in huggingface_hub to use token everywhere.

This has been discussed in:

• https://github.com/huggingface/huggingface_hub/issues/1094.
• https://github.com/huggingface/huggingface_hub/pull/928
• (related) https://github.com/huggingface/huggingface_hub/pull/1064