# Utilitários

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

O pacote `huggingface_hub` expõe uma utilidade de `logging` para controlar o nível de log do próprio pacote. Você pode importá-lo da seguinte forma:

```py
from huggingface_hub import logging
```

Em seguida, você pode definir a verbosidade para atualizar a quantidade de logs 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(...)
```

Os níveis devem ser entendidos da seguinte forma:

- `error`: exibe apenas logs críticos sobre o uso que podem resultar em um erro ou comportamento inesperado.
- `warning`: exibe logs que não são críticos, mas cujo uso pode resultar em comportamento não intencional. Além disso, logs informativos importantes podem ser exibidos.
- `info`: exibe a maioria dos logs, incluindo alguns registros detalhados sobre o que está acontecendo nos bastidores. Se algo estiver se comportando de maneira inesperada, recomendamos alternar o nível de verbosidade para este a fim de obter mais informações.
- `debug`: exibe todos os logs, incluindo alguns logs internos que podem ser usados para rastrear exatamente o que está acontecendo por baixo dos panos.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L103)

**Retorna:**

Nível de log, por exemplo, `huggingface_hub.logging.DEBUG` e `huggingface_hub.logging.INFO`.

Retorna o nível atual do logger raiz do HuggingFace Hub.

> [!TIP]
> O HuggingFace Hub possui os seguintes níveis de log:
>
> - `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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L122)

**Parâmetros:**

verbosity (`int`) : Nível de log, por exemplo, `huggingface_hub.logging.DEBUG` e `huggingface_hub.logging.INFO`.

Define o nível do logger raiz do HuggingFace Hub.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L134)

Define a verbosidade para `logging.INFO`.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L148)

Define a verbosidade para `logging.DEBUG`.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L141)

Define a verbosidade para `logging.WARNING`.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L155)

Define a verbosidade para `logging.ERROR`.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L162)

Desative a propagação das saídas de log da biblioteca. Observe que a propagação de logs é desativada por padrão.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L170)

Ative a propagação dos logs de saída da biblioteca. Desative o manipulador padrão do HuggingFace Hub para evitar registros duplicados, caso o logger raiz tenha sido configurado.

### Métodos auxiliares específicos do repositório[[huggingface_hub.utils.logging.get_logger]]

Os métodos expostos abaixo são relevantes ao modificar módulos da própria biblioteca `huggingface_hub`. O uso deles não deve ser necessário se você utiliza `huggingface_hub` e não os modifica.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/logging.py#L78)

**Parâmetros:**

name (`str`, *opcional*) : O nome do logger a ser obtido, geralmente o nome do arquivo

Retorna um logger com o nome especificado. Esta função não deve ser acessada diretamente pelos usuários da biblioteca.

Exemplo:

```python
>>> from huggingface_hub import logging

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

## Configure barras de progresso

Barras de progresso são uma ferramenta útil para exibir informações ao usuário enquanto uma tarefa de longa duração está sendo executada (por exemplo, ao baixar ou enviar arquivos). `huggingface_hub` expõe um wrapper de `tqdm` para exibir barras de progresso de forma consistente em toda a biblioteca.

Por padrão, as barras de progresso estão habilitadas. Você pode desativá-las globalmente definindo a variável de ambiente `HF_HUB_DISABLE_PROGRESS_BARS`. Você também pode habilitá-las/desativá-las usando [enable_progress_bars()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.utils.enable_progress_bars) e [disable_progress_bars](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.utils.disable_progress_bars). Se definida, a variável de ambiente tem prioridade sobre os 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()
```

### Controle específico de grupo das barras de progresso

Você também pode habilitar ou desabilitar barras de progresso para grupos específicos. Isso permite gerenciar a visibilidade das barras de progresso de forma mais granular em diferentes partes do seu aplicativo ou biblioteca. Quando uma barra de progresso é desabilitada para um grupo, todos os subgrupos sob ele também são afetados, a menos que haja uma sobrescrita explícita.

```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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/tqdm.py#L191)

**Parâmetros:**

name (`str`, *opcional*) : O nome do grupo a ser verificado; se for None, verifica a configuração global.

**Retorna:** `bool`

True se as barras de progresso estiverem desativadas, False caso contrário.

Verifique se as barras de progresso estão desativadas globalmente ou para um grupo específico.

Esta função retorna se as barras de progresso estão desativadas para um grupo específico ou globalmente. Ela verifica primeiro a variável de ambiente `HF_HUB_DISABLE_PROGRESS_BARS` e, em seguida, as configurações 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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/tqdm.py#L109)

**Parâmetros:**

name (`str`, *opcional*) : O nome do grupo para o qual as barras de progresso devem ser desativadas. Se for None, as barras de progresso são desativadas globalmente.

**Exceções:** ``Warning``

- ``Warning`` -- Se a variável de ambiente impedir alterações.

Desative as barras de progresso globalmente ou para um grupo especificado.

Esta função atualiza o estado das barras de progresso com base em um nome de grupo. Se nenhum nome de grupo for fornecido, todas as barras de progresso serão desativadas. A operação respeita a configuração da variável de ambiente `HF_HUB_DISABLE_PROGRESS_BARS`.

Funciona tanto como uma chamada regular quanto como um gerenciador de contexto: disable_progress_bars()           # desativa até enable_progress_bars() with disable_progress_bars():     # desativa para o bloco, reativa na saída ...

### 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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/tqdm.py#L159)

**Parâmetros:**

name (`str`, *opcional*) : O nome do grupo para o qual as barras de progresso devem ser habilitadas. Se for None, as barras de progresso são habilitadas globalmente.

**Exceções:** ``Warning``

- ``Warning`` -- Se a variável de ambiente impedir alterações.

Ative as barras de progresso globalmente ou para um grupo especificado.

Esta função define as barras de progresso como habilitadas para o grupo especificado ou globalmente, caso nenhum grupo seja especificado. A operação está sujeita à configuração de ambiente `HF_HUB_DISABLE_PROGRESS_BARS`.

## Configurando o backend HTTP[[huggingface_hub.set_client_factory]]

> [!TIP]
> No `huggingface_hub` v0.x, as requisições HTTP eram tratadas com `requests`, e a configuração era feita via `configure_http_backend`. Como agora usamos `httpx2`, a configuração funciona de forma diferente: você deve fornecer uma função de fábrica que não recebe argumentos e retorna um `httpx2.Client`. Você pode revisar a [implementação padrão aqui](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/utils/_http.py) para ver quais parâmetros são usados por padrão.

Em algumas configurações, você pode precisar controlar como as requisições HTTP são feitas, por exemplo, ao trabalhar atrás de um proxy. A biblioteca `huggingface_hub` permite configurar isso globalmente com [set_client_factory()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.set_client_factory). Após a configuração, todas as requisições ao Hub usarão suas configurações personalizadas. Como o `huggingface_hub` depende do `httpx2.Client` por baixo dos panos, você pode consultar a [documentação do `httpx2`](https://httpx2.pydantic.dev/advanced/clients/) para detalhes sobre os parâmetros disponíveis.

Se você está criando uma biblioteca de terceiros e precisa fazer solicitações diretas ao Hub, use [get_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.get_session) para obter um cliente `httpx2` corretamente configurado. Substitua qualquer chamada direta de `httpx2.get(...)` por `get_session().get(...)` para garantir o comportamento adequado.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_http.py#L372)

Defina a fábrica de cliente HTTP a ser usada pelo `huggingface_hub`.

A fábrica de clientes é um método que retorna um objeto `httpx2.Client`. Na primeira chamada para [get_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.get_session), a fábrica de clientes será usada para criar um novo objeto `httpx2.Client` que será compartilhado entre todas as chamadas feitas por `huggingface_hub`.

Isso pode ser útil se você estiver executando seus scripts em um ambiente específico que exija configuração personalizada (por exemplo, proxy ou certificados personalizados).

Use [get_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.get_session) para obter um `httpx2.Client` corretamente configurado.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_http.py#L405)

Obtenha um objeto `httpx2.Client`, usando a fábrica de transporte do usuário.

Este cliente é compartilhado entre todas as chamadas feitas por `huggingface_hub`. Portanto, você não deve fechá-lo manualmente.

Use [set_client_factory()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.set_client_factory) para personalizar o `httpx2.Client`.

Em casos raros, você pode querer fechar manualmente a sessão atual (por exemplo, após um `SSLError` transitório). Você pode fazer isso com [close_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.close_session). Uma nova sessão será criada automaticamente na próxima chamada para [get_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.get_session).

As sessões são sempre fechadas automaticamente quando o processo é encerrado.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_http.py#L434)

Feche o `httpx2.Client` global usado pelo `huggingface_hub`.

Se um Client for fechado, ele será recriado na próxima chamada para [get_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.get_session).

Pode ser útil, por exemplo, se um certificado SSL tiver sido atualizado.

Para código assíncrono, use [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.set_async_client_factory) para configurar um `httpx2.AsyncClient` e [get_async_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.get_async_session) para recuperar um.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_http.py#L389)

Defina a fábrica de cliente HTTP assíncrono a ser usada pelo `huggingface_hub`.

A fábrica de clientes assíncronos é um método que retorna um objeto `httpx2.AsyncClient`. Isso pode ser útil se você estiver executando seus scripts em um ambiente específico que exija configuração personalizada (por exemplo, proxy ou certificações personalizadas). Use [get_async_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.get_async_session) para obter um `httpx2.AsyncClient` configurado corretamente.

> [!WARNING]
> Diferentemente do `httpx2.Client`, que é compartilhado entre todas as chamadas feitas por `huggingface_hub`, o `httpx2.AsyncClient` não é compartilhado. Recomenda-se o uso de um gerenciador de contexto assíncrono para garantir que o cliente seja fechado corretamente ao sair do contexto.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_http.py#L421)

Retorna um objeto `httpx2.AsyncClient`, usando a fábrica de transporte do usuário.

Use [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.set_async_client_factory) para personalizar o `httpx2.AsyncClient`.

> [!WARNING]
> Diferentemente do `httpx2.Client`, que é compartilhado entre todas as chamadas feitas por `huggingface_hub`, o `httpx2.AsyncClient` não é compartilhado. Recomenda-se o uso de um gerenciador de contexto assíncrono para garantir que o cliente seja fechado corretamente ao sair do contexto.

> [!TIP]
> Diferente do cliente síncrono, o ciclo de vida do cliente assíncrono não é gerenciado automaticamente. Use um gerenciador de contexto assíncrono para tratá-lo corretamente.

### O módulo `httpx`

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

```py
from huggingface_hub.utils import httpx

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

Isso é útil principalmente para bibliotecas de terceiros construídas sobre o `huggingface_hub`. O `huggingface_hub` v1.x é construído sobre o [`httpx`](https://www.python-httpx.org/), enquanto o v2.x é construído sobre o [`httpx2`](https://httpx2.pydantic.dev/) (seu sucessor, distribuído como um pacote separado). Importar o módulo de `huggingface_hub.utils` em vez de importar o `httpx` diretamente significa que você sempre obtém a versão que o `huggingface_hub` realmente usa, e sua biblioteca permanece compatível com ambas as versões principais. Veja [esta issue](https://github.com/huggingface/huggingface_hub/issues/4802) para mais detalhes sobre o plano de migração.

> [!WARNING]
> Use isso apenas se precisar de tipos ou exceções do `httpx` (por exemplo, para capturar erros). Para fazer requisições ao Hub, use [get_session()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.get_session) conforme descrito acima.

## Tratar erros HTTP

`huggingface_hub` define seus próprios erros HTTP para refinar o `HTTPError` lançado pelo `httpx2` com informações adicionais enviadas de volta pelo servidor.

### Gerar exceção para status[[huggingface_hub.hf_raise_for_status]]

[hf_raise_for_status()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.hf_raise_for_status) é o método central para "raise for status" de qualquer solicitação feita ao Hub. Ele encapsula o `httpx2.Response.raise_for_status` base para fornecer informações adicionais. Qualquer `HTTPError` lançada é convertida em um `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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_http.py#L826)

**Parâmetros:**

response (`Response`) : Resposta do servidor.

endpoint_name (`str`, *opcional*) : Nome do endpoint que foi chamado. Se fornecido, a mensagem de erro será mais completa.

Versão interna de `response.raise_for_status()` que refina um possível HTTPError. A exceção lançada será uma instância de [HfHubHTTPError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.HfHubHTTPError).

Este helper é destinado a ser o método único para raise_for_status ao fazer uma chamada ao Hugging Face Hub.

> [!WARNING]
> Levanta quando a solicitação falhou:
>
> - [RepositoryNotFoundError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.RepositoryNotFoundError) Se o repositório de onde o download será feito não puder ser encontrado. Isso pode ocorrer porque ele não existe, porque `repo_type` não está definido corretamente ou porque o repositório é `private` e você não tem acesso. - [GatedRepoError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.GatedRepoError) Se o repositório existe, mas é restrito e o usuário não está na lista autorizada. - [RevisionNotFoundError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.RevisionNotFoundError) Se o repositório existe, mas a revisão não pôde ser encontrada. - [EntryNotFoundError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.EntryNotFoundError) Se o repositório existe, mas a entrada (por exemplo, o arquivo solicitado) não pôde ser encontrada. - [BadRequestError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.BadRequestError) Se a solicitação falhou com um erro HTTP 400 BadRequest. - [HfHubHTTPError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.HfHubHTTPError) Se a solicitação falhou por um motivo não listado acima.

### Verifique o modo offline[[huggingface_hub.is_offline_mode]]

Você pode verificar programaticamente se o modo offline está habilitado usando `is_offline_mode`. O modo offline é habilitado definindo `HF_HUB_OFFLINE=1` como variável de ambiente.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/constants.py#L197)

Indica se estamos no modo offline para o Hub.

Quando o modo offline está ativado, todas as solicitações HTTP feitas com `get_session` levantarão uma exceção `OfflineModeIsEnabled`.

Exemplo:
```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)
```

### Erros HTTP

Aqui está uma lista de erros HTTP lançados em `huggingface_hub`.

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

`HfHubHTTPError` é a classe pai para qualquer erro HTTP do HF Hub. Ela cuida da análise da resposta do servidor e formata a mensagem de erro para fornecer ao usuário o máximo de informações possível.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L90)

HTTPError para ser herdada por qualquer erro HTTP personalizado lançado no HF Hub.

Qualquer HTTPError é convertido, no mínimo, em um `HfHubHTTPError`. Se alguma informação for enviada de volta pelo servidor, ela será adicionada à mensagem de erro.

Detalhes adicionados:
- ID da solicitação obtido dos cabeçalhos, na seguinte ordem de precedência: "X-Request-Id", "X-Amzn-Trace-Id", "X-Amz-Cf-Id".
- Mensagem de erro do servidor do cabeçalho "X-Error-Message".
- Mensagem de erro do servidor, caso possamos encontrá-la no corpo da resposta.

Exemplo:
```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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L137)

Adicione informações adicionais à mensagem inicial do `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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L313)

**Parâmetros:**

repo_id (`str` ou `None`) : O id do repositório que não foi encontrado, se puder ser determinado a partir da URL da solicitação.

repo_type (`str` ou `None`) : O tipo de repositório ("model", "dataset" ou "space"), se puder ser determinado a partir da URL da solicitação.

Disparada ao tentar acessar uma URL do hf.co com um nome de repositório inválido ou com o nome de um repositório privado ao qual o usuário não tem acesso.

Exemplo:

```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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L343)

Disparada ao tentar acessar um repositório restrito para o qual o usuário não está na lista de autorizados.

Observação: deriva de `RepositoryNotFoundError` para garantir compatibilidade reversa.

Exemplo:

```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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L386)

**Parâmetros:**

repo_id (`str` ou `None`) : O id do repositório, se puder ser determinado a partir da URL da solicitação.

repo_type (`str` ou `None`) : O tipo de repositório ("model", "dataset" ou "space"), se puder ser determinado a partir da URL da solicitação.

Disparada ao tentar acessar uma URL do hf.co com um repositório válido, mas uma revisão inválida.

Exemplo:

```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]]

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L413)

Disparado por [HfApi.resolve_revision()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_api#huggingface_hub.HfApi.resolve_revision) quando uma revisão não pode ser resolvida para um hash de commit: o Hub não pôde ser acessado (modo offline, erro de conexão, tempo limite, indisponibilidade do Hub, ...) e nenhuma entrada correspondente foi encontrada no cache 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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L504)

Disparada por `hf_raise_for_status` quando o servidor retorna um erro HTTP 400.

Exemplo:

```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]]

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L422)

Disparado quando a entrada não é encontrada, seja localmente ou remotamente.

Exemplo:

```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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L440)

**Parâmetros:**

repo_id (`str` ou `None`) : O id do repositório, se puder ser determinado a partir da URL da solicitação.

repo_type (`str` ou `None`) : O tipo de repositório ("model", "dataset" ou "space"), se puder ser determinado a partir da URL da solicitação.

Disparada ao tentar acessar uma URL do hf.co com um repositório e uma revisão válidos, mas com um nome de arquivo inválido.

Exemplo:

```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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L467)

Disparada ao tentar acessar um arquivo ou snapshot que não está no disco quando a rede está desativada ou indisponível (problema de conexão). A entrada pode existir no Hub.

Exemplo:

```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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L486)

Disparado por [snapshot_download()](/docs/huggingface_hub/v2.4.0/pt/package_reference/file_download#huggingface_hub.snapshot_download) quando o Hub não pode ser acessado (offline, problema de conexão ou `local_files_only=True`) e o snapshot em cache é conhecido por estar incompleto: alguns arquivos listados na árvore em cache do repositório estão ausentes do snapshot local.

Esta é uma subclasse de `LocalEntryNotFoundError` para compatibilidade reversa.

O atributo `snapshot_path` contém o caminho para o snapshot local incompleto, permitindo que uma biblioteca a jusante localize os arquivos mais recentes em cache, mesmo que sejam conhecidos por serem incompletos.

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L26)

Lançada por [get_cached_repo_tree()](/docs/huggingface_hub/v2.4.0/pt/package_reference/file_download#huggingface_hub.get_cached_repo_tree) quando não há uma listagem de árvore em cache para a revisão solicitada.

A listagem da árvore é preenchida como efeito colateral de [snapshot_download()](/docs/huggingface_hub/v2.4.0/pt/package_reference/file_download#huggingface_hub.snapshot_download).

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

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

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L86)

Ocorrida quando uma solicitação é feita, mas a variável de ambiente `HF_HUB_OFFLINE=1` está definida.

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

`huggingface_hub` inclui um auxiliar para enviar dados de telemetria. Essas informações nos ajudam a depurar problemas e priorizar novos recursos. Os usuários podem desativar a coleta de telemetria a qualquer momento definindo a variável de ambiente `HF_HUB_DISABLE_TELEMETRY=1`. A telemetria também é desativada no modo offline (ou seja, ao definir HF_HUB_OFFLINE=1).

Se você é mantenedor de uma biblioteca de terceiros, enviar dados de telemetria é tão simples quanto fazer uma chamada para `send_telemetry`. Os dados são enviados em uma thread separada para reduzir ao máximo o impacto para os usuários.

#### 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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_telemetry.py#L19)

**Parâmetros:**

topic (`str`) : Nome do tópico que é monitorado. O tópico é usado diretamente para construir a URL. Se você quiser monitorar subtópicos, basta usar "/" como separador. Exemplos: "gradio", "transformers/examples",...

library_name (`str`, *opcional*) : O nome da biblioteca que está fazendo a requisição HTTP. Será adicionado ao cabeçalho user-agent.

library_version (`str`, *opcional*) : A versão da biblioteca que está fazendo a requisição HTTP. Será adicionada ao cabeçalho user-agent.

user_agent (`str`, `dict`, *opcional*) : As informações do user agent na forma de um dicionário ou de uma única string. Serão complementadas com informações sobre os pacotes instalados.

Envia telemetria que ajuda a rastrear o uso de diferentes bibliotecas do HF.

Esses dados de uso nos ajudam a depurar problemas e priorizar novos recursos. No entanto, entendemos que nem todos desejam compartilhar informações adicionais e respeitamos sua privacidade. Você pode desativar a coleta de telemetria definindo `HF_HUB_DISABLE_TELEMETRY=1` como variável de ambiente. A telemetria também é desativada no modo offline (ou seja, ao definir `HF_HUB_OFFLINE=1`).

A coleta de telemetria é executada em uma thread separada para minimizar o impacto para o usuário.

Exemplo:
```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` inclui validadores personalizados para validar automaticamente os argumentos dos métodos. A validação é inspirada no trabalho realizado no [Pydantic](https://pydantic-docs.helpmanual.io/) para validar type hints, mas com recursos mais limitados.

### Decorador genérico

[validate_hf_hub_args()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.utils.validate_hf_hub_args) é um decorador genérico para encapsular métodos que possuem argumentos seguindo a convenção de nomenclatura do `huggingface_hub`. Por padrão, todos os argumentos que possuem um validador implementado serão validados.

Se uma entrada não for válida, um [HFValidationError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.HFValidationError) é lançado. Apenas o primeiro valor não válido lança um erro e interrompe o processo de validação.

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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_validators.py#L42)

**Exceções:** [HFValidationError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.HFValidationError)

- [HFValidationError](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.errors.HFValidationError) -- Se uma entrada não for válida.

Valide os valores recebidos como argumento para qualquer método público de `huggingface_hub`.

O objetivo deste decorador é harmonizar a validação de argumentos reutilizados em todos os lugares. Por padrão, todos os validadores definidos são testados.

Validadores:
- [validate_repo_id()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.utils.validate_repo_id): `repo_id` deve ser `"repo_name"` ou `"namespace/repo_name"`. Namespace é um nome de usuário ou uma organização.
- `~utils.smoothly_deprecate_legacy_arguments`: Ignore `proxies` ao baixar arquivos (deve ser definido globalmente).

Exemplo:
```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]]

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/errors.py#L217)

Exceção genérica lançada pelos validadores do `huggingface_hub`.

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

### Validadores de argumentos

Os validadores também podem ser usados individualmente. A seguir, há uma lista de todos os argumentos que podem ser validados.

#### 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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_validators.py#L94)

Valide se `repo_id` é válido.

Isso não tem a intenção de substituir a validação adequada feita no Hub, mas sim de evitar inconsistências locais sempre que possível (exemplo: passar `repo_type` no `repo_id` é proibido).

Regras:
- Entre 1 e 96 caracteres.
- Ou "repo_name" ou "namespace/repo_name"
- [a-zA-Z0-9] ou "-", "_", "."
- "--" e ".." são proibidos

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

Não válido: `"datasets/foo/bar"`, `".repo_id"`, `"foo--bar"`, `"foo.git"`

Exemplo:
```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 em https://github.com/huggingface/huggingface_hub/issues/1008. Em moon-landing (repositório 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]]

Não exatamente um validador, mas também foi executado.

#### 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)
```

[Fonte](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/utils/_validators.py#L152)

Descontinuar suavemente os argumentos legados na base de código do `huggingface_hub`.

Esta função ignora alguns argumentos obsoletos dos kwargs e avisa o usuário de que eles estão sendo ignorados. O objetivo é evitar a quebra de código existente, ao mesmo tempo em que orienta o usuário para a nova maneira de fazer as coisas.

Lista de argumentos obsoletos:
- `proxies`: Para configurar proxies, o usuário deve usar a variável de ambiente HTTP_PROXY ou configurar manualmente o `httpx2.Client` usando a função [set_client_factory()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.set_client_factory).

  No huggingface_hub 0.x, `proxies` era um dicionário passado diretamente para `requests.request`. Desde o huggingface_hub 1.x, `proxies` por solicitação não são mais suportados. Em particular, não é possível configurar proxies em base por solicitação. A solução é configurá-lo globalmente usando a função [set_client_factory()](/docs/huggingface_hub/v2.4.0/pt/package_reference/utilities#huggingface_hub.set_client_factory) ou usando a variável de ambiente HTTP_PROXY.

  Para mais detalhes, consulte:
  - https://httpx2.pydantic.dev/advanced/proxies/

- `resume_download`: descontinuado sem substituto. `huggingface_hub` sempre retoma downloads sempre que possível.
- `force_filename`: descontinuado sem substituto. O nome do arquivo é sempre o mesmo do Hub.
- `local_dir_use_symlinks`: descontinuado sem substituto. O download para um diretório local não usa mais links simbólicos.