# Utilidades

## Configurar el registro[[huggingface_hub.utils.logging.get_verbosity]]

El paquete `huggingface_hub` expone una utilidad de `logging` para controlar el nivel de registro del propio paquete. Puedes importarlo de la siguiente manera:

```py
from huggingface_hub import logging
```

A continuación, puede definir la verbosidad para actualizar la cantidad de registros que verá:

```python
from huggingface_hub import logging

logging.set_verbosity_error()
logging.set_verbosity_warning()
logging.set_verbosity_info()
logging.set_verbosity_debug()

logging.set_verbosity(...)
```

Los niveles deben entenderse de la siguiente manera:

- `error`: solo muestra registros críticos sobre el uso que pueden provocar un error o un comportamiento inesperado.
- `warning`: muestra registros que no son críticos, pero cuyo uso puede provocar un comportamiento no deseado. Además, es posible que se muestren registros informativos importantes.
- `info`: muestra la mayoría de los registros, incluido algún registro detallado sobre lo que ocurre internamente. Si algo se comporta de manera inesperada, recomendamos cambiar el nivel de detalle a este para obtener más información.
- `debug`: muestra todos los registros, incluidos algunos registros internos que pueden usarse para rastrear exactamente lo que ocurre por debajo.

#### huggingface_hub.utils.logging.get_verbosity[[huggingface_hub.utils.logging.get_verbosity]]

```python
huggingface_hub.utils.logging.get_verbosity()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L103)

**Devuelve:**

Nivel de registro, p. ej., `huggingface_hub.logging.DEBUG` y `huggingface_hub.logging.INFO`.

Devuelve el nivel actual del registrador raíz de HuggingFace Hub.

> [!TIP]
> HuggingFace Hub tiene los siguientes niveles de registro:
>
> - `huggingface_hub.logging.CRITICAL`, `huggingface_hub.logging.FATAL` - `huggingface_hub.logging.ERROR` - `huggingface_hub.logging.WARNING`, `huggingface_hub.logging.WARN` - `huggingface_hub.logging.INFO` - `huggingface_hub.logging.DEBUG`

#### huggingface_hub.utils.logging.set_verbosity[[huggingface_hub.utils.logging.set_verbosity]]

```python
huggingface_hub.utils.logging.set_verbosity(verbosity: int)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L122)

**Parámetros:**

verbosity (`int`) : Nivel de registro, p. ej., `huggingface_hub.logging.DEBUG` y `huggingface_hub.logging.INFO`.

Establece el nivel del registrador raíz de HuggingFace Hub.

#### huggingface_hub.utils.logging.set_verbosity_info[[huggingface_hub.utils.logging.set_verbosity_info]]

```python
huggingface_hub.utils.logging.set_verbosity_info()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L134)

Establece la verbosidad en `logging.INFO`.

#### huggingface_hub.utils.logging.set_verbosity_debug[[huggingface_hub.utils.logging.set_verbosity_debug]]

```python
huggingface_hub.utils.logging.set_verbosity_debug()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L148)

Establece la verbosidad en `logging.DEBUG`.

#### huggingface_hub.utils.logging.set_verbosity_warning[[huggingface_hub.utils.logging.set_verbosity_warning]]

```python
huggingface_hub.utils.logging.set_verbosity_warning()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L141)

Establece la verbosidad en `logging.WARNING`.

#### huggingface_hub.utils.logging.set_verbosity_error[[huggingface_hub.utils.logging.set_verbosity_error]]

```python
huggingface_hub.utils.logging.set_verbosity_error()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L155)

Establece la verbosidad en `logging.ERROR`.

#### huggingface_hub.utils.logging.disable_propagation[[huggingface_hub.utils.logging.disable_propagation]]

```python
huggingface_hub.utils.logging.disable_propagation()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L162)

Desactive la propagación de las salidas de registro de la biblioteca. Tenga en cuenta que la propagación de registros está desactivada de forma predeterminada.

#### huggingface_hub.utils.logging.enable_propagation[[huggingface_hub.utils.logging.enable_propagation]]

```python
huggingface_hub.utils.logging.enable_propagation()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L170)

Habilite la propagación de las salidas de registro de la biblioteca. Desactive el controlador predeterminado de HuggingFace Hub para evitar el registro duplicado si el registro raíz se ha configurado.

### Métodos auxiliares específicos del repositorio[[huggingface_hub.utils.logging.get_logger]]

Los métodos expuestos a continuación son relevantes al modificar módulos de la propia biblioteca `huggingface_hub`. No debería ser necesario usarlos si utilizas `huggingface_hub` y no los modificas.

#### huggingface_hub.utils.logging.get_logger[[huggingface_hub.utils.logging.get_logger]]

```python
huggingface_hub.utils.logging.get_logger(name: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/logging.py#L78)

**Parámetros:**

name (`str`, *opcional*) : El nombre del logger a obtener, generalmente el nombre del archivo

Devuelve un registrador con el nombre especificado. Esta función no está destinada a ser accedida directamente por los usuarios de la biblioteca.

Ejemplo:

```python
>>> from huggingface_hub import logging

>>> logger = logging.get_logger(__name__)
>>> logging.set_verbosity_info()
```

## Configurar las barras de progreso

Las barras de progreso son una herramienta útil para mostrar información al usuario mientras se ejecuta una tarea de larga duración (por ejemplo, al descargar o subir archivos). `huggingface_hub` expone un envoltorio de `tqdm` para mostrar barras de progreso de manera coherente en toda la biblioteca.

Por defecto, las barras de progreso están habilitadas. Puede desactivarlas de forma global configurando la variable de entorno `HF_HUB_DISABLE_PROGRESS_BARS`. También puede activarlas o desactivarlas mediante [enable_progress_bars()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.utils.enable_progress_bars) y [disable_progress_bars](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.utils.disable_progress_bars). Si se configura, la variable de entorno tiene prioridad sobre los helpers.

```py
>>> from huggingface_hub import snapshot_download
>>> from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars

>>> # Disable progress bars globally
>>> disable_progress_bars()

>>> # Progress bar will not be shown !
>>> snapshot_download("gpt2")

>>> are_progress_bars_disabled()
True

>>> # Re-enable progress bars globally
>>> enable_progress_bars()
```

### Control específico de grupo de las barras de progreso

También puede habilitar o deshabilitar las barras de progreso para grupos específicos. Esto le permite gestionar la visibilidad de las barras de progreso de manera más granular en diferentes partes de su aplicación o biblioteca. Cuando se deshabilita una barra de progreso para un grupo, todos los subgrupos bajo él también se ven afectados, a menos que se anule explícitamente.

```py
# Disable progress bars for a specific group
>>> disable_progress_bars("peft.foo")
>>> assert not are_progress_bars_disabled("peft")
>>> assert not are_progress_bars_disabled("peft.something")
>>> assert are_progress_bars_disabled("peft.foo")
>>> assert are_progress_bars_disabled("peft.foo.bar")

# Re-enable progress bars for a subgroup
>>> enable_progress_bars("peft.foo.bar")
>>> assert are_progress_bars_disabled("peft.foo")
>>> assert not are_progress_bars_disabled("peft.foo.bar")

# Use groups with tqdm
# No progress bar for `name="peft.foo"`
>>> for _ in tqdm(range(5), name="peft.foo"):
...     pass

# Progress bar will be shown for `name="peft.foo.bar"`
>>> for _ in tqdm(range(5), name="peft.foo.bar"):
...     pass
100%|███████████████████████████████████████| 5/5 [00:00<00:00, 117817.53it/s]
```

### are_progress_bars_disabled[[huggingface_hub.utils.are_progress_bars_disabled]]

#### huggingface_hub.utils.are_progress_bars_disabled[[huggingface_hub.utils.are_progress_bars_disabled]]

```python
huggingface_hub.utils.are_progress_bars_disabled(name: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/tqdm.py#L191)

**Parámetros:**

name (`str`, *opcional*) : El nombre del grupo a verificar; si es None, verifica la configuración global.

**Devuelve:** `bool`

True si las barras de progreso están deshabilitadas, False en caso contrario.

Comprueba si las barras de progreso están deshabilitadas globalmente o para un grupo específico.

Esta función devuelve si las barras de progreso están desactivadas para un grupo dado o de forma global. Primero comprueba la variable de entorno `HF_HUB_DISABLE_PROGRESS_BARS` y luego las configuraciones programáticas.

### disable_progress_bars[[huggingface_hub.utils.disable_progress_bars]]

#### huggingface_hub.utils.disable_progress_bars[[huggingface_hub.utils.disable_progress_bars]]

```python
huggingface_hub.utils.disable_progress_bars(name: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/tqdm.py#L109)

**Parámetros:**

name (`str`, *opcional*) : El nombre del grupo para el cual se desactivarán las barras de progreso. Si es None, las barras de progreso se desactivan globalmente.

**Excepciones:** ``Warning``

- ``Warning`` -- Si la variable de entorno impide los cambios.

Desactiva las barras de progreso de forma global o para un grupo especificado.

Esta función actualiza el estado de las barras de progreso en función de un nombre de grupo. Si no se proporciona un nombre de grupo, se desactivan todas las barras de progreso. La operación respeta la configuración de la variable de entorno `HF_HUB_DISABLE_PROGRESS_BARS`.

Funciona tanto como una llamada regular como como un gestor de contexto: disable_progress_bars()           # desactiva hasta enable_progress_bars()
with disable_progress_bars():     # desactiva para el bloque, reactiva al salir
...

### enable_progress_bars[[huggingface_hub.utils.enable_progress_bars]]

#### huggingface_hub.utils.enable_progress_bars[[huggingface_hub.utils.enable_progress_bars]]

```python
huggingface_hub.utils.enable_progress_bars(name: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/tqdm.py#L159)

**Parámetros:**

name (`str`, *opcional*) : El nombre del grupo para el que se habilitarán las barras de progreso. Si es None, las barras de progreso se habilitan globalmente.

**Excepciones:** ``Warning``

- ``Warning`` -- Si la variable de entorno impide los cambios.

Habilite las barras de progreso de forma global o para un grupo especificado.

Esta función habilita las barras de progreso para el grupo especificado o de forma global si no se especifica ningún grupo. La operación está sujeta a la configuración de entorno `HF_HUB_DISABLE_PROGRESS_BARS`.

## Configuración del backend HTTP[[huggingface_hub.set_client_factory]]

> [!TIP]
> En `huggingface_hub` v0.x, las solicitudes HTTP se manejaban con `requests` y la configuración se hacía mediante `configure_http_backend`. Dado que ahora usamos `httpx2`, la configuración funciona de manera diferente: debes proporcionar una función de fábrica que no tome argumentos y devuelva un `httpx2.Client`. Puedes revisar la [implementación predeterminada aquí](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py) para ver qué parámetros se usan de forma predeterminada.

En algunas configuraciones, es posible que necesites controlar cómo se realizan las solicitudes HTTP, por ejemplo, al trabajar detrás de un proxy. La biblioteca `huggingface_hub` te permite configurar esto de forma global con [set_client_factory()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.set_client_factory). Después de la configuración, todas las solicitudes al Hub utilizarán tus ajustes personalizados. Dado que `huggingface_hub` se basa en `httpx2.Client` internamente, puedes consultar la [documentación de `httpx2`](https://httpx2.pydantic.dev/advanced/clients/) para obtener detalles sobre los parámetros disponibles.

Si estás desarrollando una biblioteca de terceros y necesitas realizar solicitudes directas al Hub, usa [get_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.get_session) para obtener un cliente `httpx2` correctamente configurado. Reemplaza cualquier llamada directa a `httpx2.get(...)` con `get_session().get(...)` para garantizar un comportamiento adecuado.

#### huggingface_hub.set_client_factory[[huggingface_hub.set_client_factory]]

```python
huggingface_hub.set_client_factory(client_factory: Callable)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py#L372)

Establezca la fábrica de clientes HTTP que usará `huggingface_hub`.

La fábrica de clientes es un método que devuelve un objeto `httpx2.Client`. En la primera llamada a [get_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.get_session), la fábrica de clientes se utilizará para crear un nuevo objeto `httpx2.Client` que se compartirá entre todas las llamadas realizadas por `huggingface_hub`.

Esto puede ser útil si ejecutas tus scripts en un entorno específico que requiere una configuración personalizada (p. ej., un proxy o certificados personalizados).

Use [get_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.get_session) para obtener un `httpx2.Client` correctamente configurado.

#### huggingface_hub.get_session[[huggingface_hub.get_session]]

```python
huggingface_hub.get_session()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py#L405)

Obtenga un objeto `httpx2.Client` utilizando la fábrica de transporte del usuario.

Este cliente se comparte entre todas las llamadas realizadas por `huggingface_hub`. Por lo tanto, no debe cerrarse manualmente.

Use [set_client_factory()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.set_client_factory) para personalizar el `httpx2.Client`.

En casos raros, es posible que desee cerrar manualmente la sesión actual (por ejemplo, después de un `SSLError` transitorio). Puede hacer esto con [close_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.close_session). Se creará automáticamente una nueva sesión en la siguiente llamada a [get_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.get_session).

Las sesiones siempre se cierran automáticamente cuando el proceso termina.

#### huggingface_hub.close_session[[huggingface_hub.close_session]]

```python
huggingface_hub.close_session()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py#L434)

Cierra el `httpx2.Client` global utilizado por `huggingface_hub`.

Si un Client se cierra, se volverá a crear en la siguiente llamada a [get_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.get_session).

Puede ser útil, por ejemplo, si se ha actualizado un certificado SSL.

Para código asíncrono, use [set_async_client_factory()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.set_async_client_factory) para configurar un `httpx2.AsyncClient` y [get_async_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.get_async_session) para obtener uno.

#### huggingface_hub.set_async_client_factory[[huggingface_hub.set_async_client_factory]]

```python
huggingface_hub.set_async_client_factory(async_client_factory: Callable)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py#L389)

Establezca la fábrica de clientes HTTP asíncronos que usará `huggingface_hub`.

La fábrica de clientes asíncronos es un método que devuelve un objeto `httpx2.AsyncClient`. Esto puede ser útil si ejecutas tus scripts en un entorno específico que requiera una configuración personalizada (p. ej., un proxy o certificados personalizados). Usa [get_async_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.get_async_session) para obtener un `httpx2.AsyncClient` correctamente configurado.

> [!WARNING]
> A diferencia del `httpx2.Client`, que se comparte entre todas las llamadas realizadas por `huggingface_hub`, el `httpx2.AsyncClient` no se comparte. Se recomienda usar un gestor de contexto asíncrono para garantizar que el cliente se cierre correctamente al salir del contexto.

#### huggingface_hub.get_async_session[[huggingface_hub.get_async_session]]

```python
huggingface_hub.get_async_session()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py#L421)

Devuelve un objeto `httpx2.AsyncClient`, utilizando la fábrica de transporte del usuario.

Use [set_async_client_factory()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.set_async_client_factory) para personalizar el `httpx2.AsyncClient`.

> [!WARNING]
> A diferencia del `httpx2.Client`, que se comparte entre todas las llamadas realizadas por `huggingface_hub`, el `httpx2.AsyncClient` no se comparte. Se recomienda usar un gestor de contexto asíncrono para garantizar que el cliente se cierre correctamente al salir del contexto.

> [!TIP]
> A diferencia del cliente síncrono, el ciclo de vida del cliente asíncrono no se gestiona automáticamente. Utilice un gestor de contexto asíncrono para administrarlo correctamente.

### El módulo `httpx`

`huggingface_hub` reexporta la biblioteca HTTP que utiliza internamente como `huggingface_hub.utils.httpx`:

```py
from huggingface_hub.utils import httpx

try:
    ...
except httpx.HTTPError:
    ...
```

Esto resulta útil principalmente para bibliotecas de terceros construidas sobre `huggingface_hub`. `huggingface_hub` v1.x se basa en [`httpx`](https://www.python-httpx.org/), mientras que v2.x se basa en [`httpx2`](https://httpx2.pydantic.dev/) (su sucesor, distribuido como un paquete independiente). Importar el módulo desde `huggingface_hub.utils` en lugar de importar `httpx` directamente significa que siempre obtienes la versión que `huggingface_hub` utiliza realmente, y tu biblioteca se mantiene compatible con ambas versiones principales. Consulta [este problema](https://github.com/huggingface/huggingface_hub/issues/4802) para obtener más detalles sobre el plan de migración.

> [!WARNING]
> Utiliza esto solo si necesitas tipos o excepciones de `httpx` (p. ej., para capturar errores). Para realizar solicitudes al Hub, usa [get_session()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.get_session) como se describió anteriormente.

## Gestionar errores HTTP

`huggingface_hub` define sus propios errores HTTP para refinar el `HTTPError` lanzado por `httpx2` con información adicional enviada por el servidor.

### Generar una excepción para el estado[[huggingface_hub.hf_raise_for_status]]

[hf_raise_for_status()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.hf_raise_for_status) está diseñado para ser el método central para "lanzar una excepción por estado" desde cualquier solicitud realizada al Hub. Envuelve el método base `httpx2.Response.raise_for_status` para proporcionar información adicional. Cualquier `HTTPError` lanzado se convierte en un `HfHubHTTPError`.

```py
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("\n`create_commit` expects the repository to exist.")
    raise
```

#### huggingface_hub.hf_raise_for_status[[huggingface_hub.hf_raise_for_status]]

```python
huggingface_hub.hf_raise_for_status(response: Response, endpoint_name: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py#L826)

**Parámetros:**

response (`Response`) : Respuesta del servidor.

endpoint_name (`str`, *opcional*) : Nombre del punto de acceso que se ha llamado. Si se proporciona, el mensaje de error será más completo.

Versión interna de `response.raise_for_status()` que refinará un posible HTTPError. La excepción lanzada será una instancia de [HfHubHTTPError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.HfHubHTTPError).

Este helper está diseñado para ser el método único para raise_for_status al realizar una llamada al Hugging Face Hub.

> [!WARNING]
> Se lanza cuando la solicitud ha fallado:
>
> - [RepositoryNotFoundError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) Si no se puede encontrar el repositorio del que se va a descargar. Esto puede deberse a que no existe, a que `repo_type` no está configurado correctamente o a que el repositorio es `private` y no tienes acceso. - [GatedRepoError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.GatedRepoError) Si el repositorio existe pero está restringido y el usuario no está en la lista autorizada. - [RevisionNotFoundError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) Si el repositorio existe pero no se pudo encontrar la revisión. - [EntryNotFoundError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.EntryNotFoundError) Si el repositorio existe pero no se pudo encontrar la entrada (p. ej., el archivo solicitado). - [BadRequestError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.BadRequestError) Si la solicitud falló con un error HTTP 400 BadRequest. - [HfHubHTTPError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.HfHubHTTPError) Si la solicitud falló por un motivo no listado anteriormente.

### Comprobar el modo sin conexión[[huggingface_hub.is_offline_mode]]

Puede comprobar de forma programática si el modo sin conexión está habilitado mediante `is_offline_mode`. El modo sin conexión se habilita estableciendo `HF_HUB_OFFLINE=1` como variable de entorno.

#### huggingface_hub.is_offline_mode[[huggingface_hub.is_offline_mode]]

```python
huggingface_hub.is_offline_mode()
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/constants.py#L197)

Indica si estamos en modo sin conexión para el Hub.

Cuando el modo sin conexión está habilitado, todas las solicitudes HTTP realizadas con `get_session` lanzarán una excepción `OfflineModeIsEnabled`.

Ejemplo:
```py
from huggingface_hub import is_offline_mode

def list_files(repo_id: str):
    if is_offline_mode():
        ... # list files from local cache (degraded experience but still functional)
    else:
        ... # list files from Hub (complete experience)
```

### Errores HTTP

Aquí hay una lista de los errores HTTP que se lanzan en `huggingface_hub`.

#### HfHubHTTPError[[huggingface_hub.errors.HfHubHTTPError]]

`HfHubHTTPError` es la clase padre de cualquier error HTTP de HF Hub. Se encarga de analizar la respuesta del servidor y formatear el mensaje de error para proporcionar al usuario la mayor cantidad de información posible.

#### huggingface_hub.errors.HfHubHTTPError[[huggingface_hub.errors.HfHubHTTPError]]

```python
huggingface_hub.errors.HfHubHTTPError(message: str, response: Response, server_message: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L90)

HTTPError para heredar en cualquier error HTTP personalizado lanzado en HF Hub.

Cualquier HTTPError se convierte al menos en un `HfHubHTTPError`. Si el servidor devuelve alguna información, se añadirá al mensaje de error.

Detalles añadidos:
- El ID de solicitud se obtiene de las cabeceras en el siguiente orden de precedencia: "X-Request-Id", "X-Amzn-Trace-Id", "X-Amz-Cf-Id".
- Mensaje de error del servidor de la cabecera "X-Error-Message".
- Mensaje de error del servidor si se encuentra uno en el cuerpo de la respuesta.

Ejemplo:
```py
    import httpx2
    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
```

#### append_to_message[[huggingface_hub.errors.HfHubHTTPError.append_to_message]]

```python
append_to_message(additional_message: str)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L137)

Añade información adicional al mensaje inicial de `HfHubHTTPError`.

#### RepositoryNotFoundError[[huggingface_hub.errors.RepositoryNotFoundError]]

#### huggingface_hub.errors.RepositoryNotFoundError[[huggingface_hub.errors.RepositoryNotFoundError]]

```python
huggingface_hub.errors.RepositoryNotFoundError(message: str, response: Response, server_message: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L313)

**Parámetros:**

repo_id (`str` o `None`) : El identificador del repositorio que no se encontró, si se pudo determinar a partir de la URL de la solicitud.

repo_type (`str` o `None`) : El tipo de repositorio ("model", "dataset" o "space"), si se pudo determinar a partir de la URL de la solicitud.

Se lanza al intentar acceder a una URL de hf.co con un nombre de repositorio no válido, o con el nombre de un repositorio privado al que el usuario no tiene acceso.

Ejemplo:

```py
>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.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 and your token has the required permissions.
Invalid username or password.
```

#### GatedRepoError[[huggingface_hub.errors.GatedRepoError]]

#### huggingface_hub.errors.GatedRepoError[[huggingface_hub.errors.GatedRepoError]]

```python
huggingface_hub.errors.GatedRepoError(message: str, response: Response, server_message: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L343)

Se genera al intentar acceder a un repositorio con acceso restringido para el cual el usuario no está en la lista de autorizados.

Nota: deriva de `RepositoryNotFoundError` para garantizar la compatibilidad hacia atrás.

Ejemplo:

```py
>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.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.
```

#### RevisionNotFoundError[[huggingface_hub.errors.RevisionNotFoundError]]

#### huggingface_hub.errors.RevisionNotFoundError[[huggingface_hub.errors.RevisionNotFoundError]]

```python
huggingface_hub.errors.RevisionNotFoundError(message: str, response: Response, server_message: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L386)

**Parámetros:**

repo_id (`str` o `None`) : El identificador del repositorio, si se pudo determinar a partir de la URL de la solicitud.

repo_type (`str` o `None`) : El tipo de repositorio ("model", "dataset" o "space"), si se pudo determinar a partir de la URL de la solicitud.

Se lanza al intentar acceder a una URL de hf.co con un repositorio válido pero una revisión no válida.

Ejemplo:

```py
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.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.
```

#### RevisionResolutionError[[huggingface_hub.errors.RevisionResolutionError]]

#### huggingface_hub.errors.RevisionResolutionError[[huggingface_hub.errors.RevisionResolutionError]]

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L413)

Se genera mediante [HfApi.resolve_revision()](/docs/huggingface_hub/main/es/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) cuando una revisión no se puede resolver a un hash de commit: no se pudo acceder al Hub (modo sin conexión, error de conexión, tiempo de espera agotado, caída del Hub, ...) y no se encontró ninguna entrada coincidente en la caché local.

#### BadRequestError[[huggingface_hub.errors.BadRequestError]]

#### huggingface_hub.errors.BadRequestError[[huggingface_hub.errors.BadRequestError]]

```python
huggingface_hub.errors.BadRequestError(message: str, response: Response, server_message: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L504)

Se genera mediante `hf_raise_for_status` cuando el servidor devuelve un error HTTP 400.

Ejemplo:

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

#### EntryNotFoundError[[huggingface_hub.errors.EntryNotFoundError]]

#### huggingface_hub.errors.EntryNotFoundError[[huggingface_hub.errors.EntryNotFoundError]]

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L422)

Se genera cuando la entrada no se encuentra, ya sea local o remotamente.

Ejemplo:

```py
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)
```

#### RemoteEntryNotFoundError[[huggingface_hub.errors.RemoteEntryNotFoundError]]

#### huggingface_hub.errors.RemoteEntryNotFoundError[[huggingface_hub.errors.RemoteEntryNotFoundError]]

```python
huggingface_hub.errors.RemoteEntryNotFoundError(message: str, response: Response, server_message: str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L440)

**Parámetros:**

repo_id (`str` o `None`) : El identificador del repositorio, si se pudo determinar a partir de la URL de la solicitud.

repo_type (`str` o `None`) : El tipo de repositorio ("model", "dataset" o "space"), si se pudo determinar a partir de la URL de la solicitud.

Se lanza al intentar acceder a una URL de hf.co con un repositorio y una revisión válidos, pero con un nombre de archivo no válido.

Ejemplo:

```py
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.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.
```

#### LocalEntryNotFoundError[[huggingface_hub.errors.LocalEntryNotFoundError]]

#### huggingface_hub.errors.LocalEntryNotFoundError[[huggingface_hub.errors.LocalEntryNotFoundError]]

```python
huggingface_hub.errors.LocalEntryNotFoundError(message: str)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L467)

Se genera al intentar acceder a un archivo o instantánea que no está en el disco cuando la red está deshabilitada o no está disponible (problema de conexión). La entrada puede existir en el Hub.

Ejemplo:

```py
>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.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.
```

#### IncompleteSnapshotError[[huggingface_hub.errors.IncompleteSnapshotError]]

#### huggingface_hub.errors.IncompleteSnapshotError[[huggingface_hub.errors.IncompleteSnapshotError]]

```python
huggingface_hub.errors.IncompleteSnapshotError(message: str, snapshot_path: str)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L486)

Se lanza mediante [snapshot_download()](/docs/huggingface_hub/main/es/package_reference/file_download#huggingface_hub.snapshot_download) cuando no se puede acceder al Hub (sin conexión, problema de conexión o `local_files_only=True`) y se sabe que la instantánea en caché está incompleta: faltan en la instantánea local algunos de los archivos enumerados en el árbol en caché del repositorio.

Esta es una subclase de `LocalEntryNotFoundError` por compatibilidad con versiones anteriores.

El atributo `snapshot_path` contiene la ruta de la instantánea local incompleta, de modo que una biblioteca de nivel inferior pueda localizar los archivos más recientes en caché, aunque se sepa que están incompletos.

#### CachedRepoTreeNotFoundError[[huggingface_hub.errors.CachedRepoTreeNotFoundError]]

#### huggingface_hub.errors.CachedRepoTreeNotFoundError[[huggingface_hub.errors.CachedRepoTreeNotFoundError]]

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L26)

Se genera mediante [get_cached_repo_tree()](/docs/huggingface_hub/main/es/package_reference/file_download#huggingface_hub.get_cached_repo_tree) cuando no hay un listado de árbol en caché para la revisión solicitada.

La lista del árbol se genera como efecto secundario de [snapshot_download()](/docs/huggingface_hub/main/es/package_reference/file_download#huggingface_hub.snapshot_download).

#### OfflineModeIsEnabled[[huggingface_hub.errors.OfflineModeIsEnabled]]

#### huggingface_hub.errors.OfflineModeIsEnabled[[huggingface_hub.errors.OfflineModeIsEnabled]]

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L86)

Se produce cuando se realiza una solicitud pero `HF_HUB_OFFLINE=1` está establecido como variable de entorno.

## Telemetría[[huggingface_hub.utils.send_telemetry]]

`huggingface_hub` incluye un helper para enviar datos de telemetría. Esta información nos ayuda a depurar problemas y a priorizar nuevas funciones. Los usuarios pueden deshabilitar la recopilación de telemetría en cualquier momento estableciendo la variable de entorno `HF_HUB_DISABLE_TELEMETRY=1`. La telemetría también se deshabilita en modo sin conexión (es decir, al establecer HF_HUB_OFFLINE=1).

Si eres mantenedor de una biblioteca de terceros, enviar datos de telemetría es tan sencillo como hacer una llamada a `send_telemetry`. Los datos se envían en un hilo separado para reducir al máximo el impacto para los usuarios.

#### huggingface_hub.utils.send_telemetry[[huggingface_hub.utils.send_telemetry]]

```python
huggingface_hub.utils.send_telemetry(topic: str, library_name: str | None = None, library_version: str | None = None, user_agent: dict | str | None = None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_telemetry.py#L19)

**Parámetros:**

topic (`str`) : Nombre del tema que se monitorea. El tema se utiliza directamente para construir la URL. Si desea monitorear subtemas, simplemente use "/" como separador. Ejemplos: "gradio", "transformers/examples",...

library_name (`str`, *opcional*) : El nombre de la biblioteca que está realizando la solicitud HTTP. Se añadirá a la cabecera user-agent.

library_version (`str`, *opcional*) : La versión de la biblioteca que realiza la solicitud HTTP. Se añadirá al encabezado user-agent.

user_agent (`str`, `dict`, *opcional*) : La información del agente de usuario en forma de un diccionario o una sola cadena de caracteres. Se completará con información sobre los paquetes instalados.

Envía telemetría que ayuda a rastrear el uso de diferentes bibliotecas de HF.

Estos datos de uso nos ayudan a depurar problemas y a priorizar nuevas funciones. Sin embargo, entendemos que no todo el mundo desea compartir información adicional y respetamos su privacidad. Puede deshabilitar la recopilación de telemetría estableciendo `HF_HUB_DISABLE_TELEMETRY=1` como variable de entorno. La telemetría también se deshabilita en modo sin conexión (es decir, al establecer `HF_HUB_OFFLINE=1`).

La recopilación de telemetría se ejecuta en un hilo separado para minimizar el impacto en el usuario.

Ejemplo:
```py
>>> 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"},
... )
```

## Validadores

`huggingface_hub` incluye validadores personalizados para validar automáticamente los argumentos de los métodos. La validación se inspira en el trabajo realizado en [Pydantic](https://pydantic-docs.helpmanual.io/) para validar las anotaciones de tipos, pero con funciones más limitadas.

### Decorador genérico

[validate_hf_hub_args()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.utils.validate_hf_hub_args) es un decorador genérico para encapsular métodos que tienen argumentos que siguen la nomenclatura de `huggingface_hub`. De forma predeterminada, se validan todos los argumentos para los que se ha implementado un validador.

Si una entrada no es válida, se lanza un [HFValidationError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.HFValidationError). Solo el primer valor no válido lanza un error y detiene el proceso de validación.

Uso:

```py
>>> 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[[huggingface_hub.utils.validate_hf_hub_args]]

#### huggingface_hub.utils.validate_hf_hub_args[[huggingface_hub.utils.validate_hf_hub_args]]

```python
huggingface_hub.utils.validate_hf_hub_args(fn: ~CallableT)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_validators.py#L42)

**Excepciones:** [HFValidationError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.HFValidationError)

- [HFValidationError](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.errors.HFValidationError) -- Si una entrada no es válida.

Valida los valores recibidos como argumento para cualquier método público de `huggingface_hub`.

El objetivo de este decorador es armonizar la validación de argumentos reutilizados en todas partes. De forma predeterminada, se prueban todos los validadores definidos.

Validadores:
- [validate_repo_id()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.utils.validate_repo_id): `repo_id` debe ser `"repo_name"` o `"namespace/repo_name"`. El namespace es un nombre de usuario o una organización.
- `~utils.smoothly_deprecate_legacy_arguments`: Ignorar `proxies` al descargar archivos (debe configurarse de forma global).

Ejemplo:
```py
>>> 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'.
```

#### HFValidationError[[huggingface_hub.errors.HFValidationError]]

#### huggingface_hub.errors.HFValidationError[[huggingface_hub.errors.HFValidationError]]

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/errors.py#L217)

Excepción genérica lanzada por los validadores de `huggingface_hub`.

Hereda de [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError).

### Validadores de argumentos

Los validadores también se pueden usar de forma individual. A continuación se muestra una lista de todos los argumentos que se pueden validar.

#### repo_id[[huggingface_hub.utils.validate_repo_id]]

#### huggingface_hub.utils.validate_repo_id[[huggingface_hub.utils.validate_repo_id]]

```python
huggingface_hub.utils.validate_repo_id(repo_id: str | None)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_validators.py#L94)

Valida que `repo_id` sea válido.

Esto no pretende sustituir la validación adecuada realizada en el Hub, sino evitar las inconsistencias locales siempre que sea posible (por ejemplo, pasar `repo_type` en `repo_id` está prohibido).

Reglas:
- Entre 1 y 96 caracteres.
- "repo_name" o "namespace/repo_name"
- [a-zA-Z0-9] o "-", "_", "."
- "--" y ".." están prohibidos

Válido: `"foo"`, `"foo/bar"`, `"123"`, `"Foo-BAR_foo.bar123"`

No válido: `"datasets/foo/bar"`, `".repo_id"`, `"foo--bar"`, `"foo.git"`

Ejemplo:
```py
>>> 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'.
```

Discutido en https://github.com/huggingface/huggingface_hub/issues/1008. En moon-landing (repositorio interno):
- 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_legacy_arguments[[huggingface_hub.utils._validators.smoothly_deprecate_legacy_arguments]]

No es exactamente un validador, pero también se ejecutó.

#### huggingface_hub.utils._validators.smoothly_deprecate_legacy_arguments[[huggingface_hub.utils._validators.smoothly_deprecate_legacy_arguments]]

```python
huggingface_hub.utils._validators.smoothly_deprecate_legacy_arguments(fn_name: str, kwargs: dict)
```

[Fuente](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_validators.py#L152)

Deprecar de forma gradual los argumentos heredados en la base de código de `huggingface_hub`.

Esta función ignora algunos argumentos obsoletos de los kwargs y avisa al usuario de que se están ignorando. El objetivo es evitar romper el código existente mientras se guía al usuario hacia la nueva forma de hacer las cosas.

Lista de argumentos obsoletos:
- `proxies`: Para configurar los proxies, el usuario debe usar la variable de entorno HTTP_PROXY o configurar manualmente el `httpx2.Client` mediante la función [set_client_factory()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.set_client_factory).

  En huggingface_hub 0.x, `proxies` era un diccionario que se pasaba directamente a `requests.request`. Desde huggingface_hub 1.x, ya no se admiten `proxies` por solicitud. En particular, no es posible configurar proxies a nivel de solicitud. La solución es configurarlo de forma global mediante la función [set_client_factory()](/docs/huggingface_hub/main/es/package_reference/utilities#huggingface_hub.set_client_factory) o utilizando la variable de entorno HTTP_PROXY.

  Para más detalles, consulte:
  - https://httpx2.pydantic.dev/advanced/proxies/

- `resume_download`: obsoleto sin reemplazo. `huggingface_hub` siempre reanuda las descargas cuando es posible.
- `force_filename`: obsoleto sin reemplazo. El nombre de archivo siempre es el mismo que en el Hub.
- `local_dir_use_symlinks`: obsoleto sin reemplazo. La descarga en un directorio local ya no utiliza enlaces simbólicos.