# API de sistema de arquivos

A classe `HfFileSystem` fornece uma interface de arquivo pythonic para o Hugging Face Hub com base no [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/).

## HfFileSystem[[huggingface_hub.HfFileSystem]]

`HfFileSystem` é baseado em [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), portanto é compatível com a maioria das APIs que ele oferece. Para mais detalhes, consulte [nossa guia](../guides/hf_file_system) e a [API Reference](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem) do fsspec.

#### huggingface_hub.HfFileSystem[[huggingface_hub.HfFileSystem]]

```python
huggingface_hub.HfFileSystem(*args, **kwargs)
```

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

**Parâmetros:**

endpoint (`str`, *opcional*) : Endpoint do Hub. Padrão é .

token (`bool` ou `str`, *opcional*) : Um token de acesso do usuário válido (string). O padrão é o token salvo localmente, que é o método recomendado para autenticação (veja https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Para desabilitar a autenticação, passe `False`.

block_size (`int`, *opcional*) : Tamanho do bloco para leitura e gravação de arquivos.

expand_info (`bool`, *opcional*) : Se deve expandir as informações dos arquivos.

max_workers (`int`, *opcional*) : Número máximo de solicitações concorrentes usadas para listar grandes diretórios em paralelo (veja [find()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_file_system#huggingface_hub.HfFileSystem.find)). O valor padrão é 16. Defina como 1 para desativar listagens paralelas.

live_follow (`bool`, *opcional*) : Se deve acompanhar as alterações nos arquivos dos buckets conforme elas ocorrem no Hub, para que as listagens em cache permaneçam atualizadas sem chamadas manuais de [HfFileSystem.invalidate_cache()](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_file_system#huggingface_hub.HfFileSystem.invalidate_cache). Quando habilitado, listar um bucket abre uma conexão em segundo plano para o feed de eventos do Hub correspondente a esse bucket. Não tem efeito em repositórios de modelos, datasets e spaces (o Hub não fornece alterações para esses tipos).

- ****storage_options** (`dict`, *opcional*) : Opções adicionais para o sistema de arquivos. Consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.__init__).

Acesse um repositório remoto do Hugging Face Hub como se fosse um sistema de arquivos local.

> [!WARNING]
> [HfFileSystem](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_file_system#huggingface_hub.HfFileSystem) oferece compatibilidade com fsspec, o que é útil para bibliotecas que a exigem (por exemplo, ler conjuntos de dados do Hugging Face diretamente com `pandas`). No entanto, isso introduz sobrecarga adicional devido a essa camada de compatibilidade. Para melhor desempenho e confiabilidade, recomenda-se usar os métodos de `HfApi` sempre que possível.

O sistema de arquivos suporta caminhos para o protocolo `hf://`, que segue os seguintes esquemas de URL:

* Repositórios de Modelos, Datasets e Spaces:

```
hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>
```

* Buckets (armazenamento genérico):

```
hf://buckets/<bucket-id>/<path/in/bucket>
```

Nota: ao usar o [HfFileSystem](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_file_system#huggingface_hub.HfFileSystem) diretamente, a passagem do prefixo de protocolo `hf://` é opcional nos caminhos.

Uso:

```python
>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)
```

Especifique um token para autenticação:
```python
>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)
```

#### cp_file[[huggingface_hub.HfFileSystem.cp_file]]

```python
cp_file(path1: str, path2: str, revision: str | None = None, **kwargs)
```

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

**Parâmetros:**

path1 (`str`) : Caminho de origem para copiar.

path2 (`str`) : Caminho de destino para copiar.

revision (`str`, *opcional*) : A revisão do git a ser copiada.

Copie um arquivo dentro ou entre repositórios, ou para um bucket.

> [!WARNING]
> Observação: Sempre que possível, use `HfApi.upload_file()` para obter melhor desempenho.

#### existe[[huggingface_hub.HfFileSystem.exists]]

```python
exists(path, **kwargs)
```

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

**Parâmetros:**

path (`str`) : Caminho a verificar.

**Retorna:** `bool`

True se o arquivo existir, False caso contrário.

Verifique se um arquivo existe.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.exists).

> [!WARNING]
> Observação: Sempre que possível, use `HfApi.file_exists()` para melhor desempenho.

#### find[[huggingface_hub.HfFileSystem.find]]

```python
find(path: str, maxdepth: int | None = None, withdirs: bool = False, detail: bool = False, refresh: bool = False, revision: str | None = None, **kwargs)
```

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

**Parâmetros:**

path (`str`) : Caminho raiz para listar os arquivos.

maxdepth (`int`, *opcional*) : Profundidade máxima para descer em subdiretórios.

withdirs (`bool`, *opcional*) : Inclui caminhos de diretórios na saída. O valor padrão é False.

detail (`bool`, *opcional*) : Se True, retorna um dicionário mapeando caminhos para informações de arquivo. O padrão é False.

refresh (`bool`, *opcional*) : Se True, ignora o cache e busca os dados mais recentes. O padrão é False.

revision (`str`, *opcional*) : A revisão git a ser listada.

**Retorna:** `Union[list[str], dict[str, dict[str, Any]]]`

Lista de caminhos ou dicionário de informações de arquivo.

Liste todos os arquivos abaixo do caminho.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.find).

> [!TIP]
> Repositórios grandes são listados diretório por diretório, em paralelo, para contornar a paginação baseada em cursor do endpoint `tree` do Hub. Ajuste isso com o argumento `max_workers` de [HfFileSystem](/docs/huggingface_hub/v2.4.0/pt/package_reference/hf_file_system#huggingface_hub.HfFileSystem).

#### get_file[[huggingface_hub.HfFileSystem.get_file]]

```python
get_file(rpath, lpath = None, callback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>, outfile = None, **kwargs)
```

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

**Parâmetros:**

rpath (`str`) : Caminho remoto para download.

lpath (`str`, *opcional*) : Caminho local para o download. Pode ser omitido se `outfile` for fornecido.

callback (`Callback`, *optional*) : Optional callback to track download progress. Defaults to no callback.

outfile (`IO`, *opcional*) : Objeto semelhante a arquivo opcional para gravação. Se fornecido, `lpath` é ignorado.

Copiar um arquivo remoto individual para o local.

> [!WARNING]
> Nota: Sempre que possível, use `HfApi.hf_hub_download()` ou `HfApi.download_bucket_files` para melhor desempenho.

#### glob[[huggingface_hub.HfFileSystem.glob]]

```python
glob(path: str, maxdepth: int | None = None, **kwargs)
```

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

**Parâmetros:**

path (`str`) : Padrão de caminho para corresponder.

maxdepth (`int`, *opcional*) : Profundidade máxima para descer nos diretórios. Por padrão, sem limite.

**Retorna:** `list[str]`

Lista de caminhos que correspondem ao padrão.

Encontre arquivos por correspondência de glob.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.glob).

#### info[[huggingface_hub.HfFileSystem.info]]

```python
info(path: str, refresh: bool = False, revision: str | None = None, **kwargs)
```

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

**Parâmetros:**

path (`str`) : Caminho para obter informações.

refresh (`bool`, *opcional*) : Se True, ignora o cache e busca os dados mais recentes. O padrão é False.

revision (`str`, *opcional*) : A revisão do git de onde obter as informações.

**Retorna:** `dict[str, Any]`

Dicionário contendo informações do arquivo (tipo, tamanho, informações do commit, etc.).

Obtém informações sobre um arquivo ou diretório.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.info).

> [!WARNING]
> Nota: Sempre que possível, use `HfApi.get_paths_info()` ou `HfApi.repo_info()` para melhor desempenho (ou `HfApi.get_bucket_paths_info()` ou `HfApi.bucket_info()` para buckets)

#### invalidate_cache[[huggingface_hub.HfFileSystem.invalidate_cache]]

```python
invalidate_cache(path: str | None = None)
```

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

**Parâmetros:**

path (`str`, *opcional*) : Caminho a ser removido do cache. Se não for fornecido, o cache inteiro será limpo.

Limpe o cache para um caminho específico.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.invalidate_cache).

#### isdir[[huggingface_hub.HfFileSystem.isdir]]

```python
isdir(path)
```

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

**Parâmetros:**

path (`str`) : Caminho a verificar.

**Retorna:** `bool`

True se o path for um diretório, False caso contrário.

Verifique se um caminho é um diretório.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isdir).

#### isfile[[huggingface_hub.HfFileSystem.isfile]]

```python
isfile(path)
```

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

**Parâmetros:**

path (`str`) : Caminho a verificar.

**Retorna:** `bool`

True se o path for um arquivo, False caso contrário.

Verifique se um caminho é um arquivo.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.isfile).

#### ls[[huggingface_hub.HfFileSystem.ls]]

```python
ls(path: str, detail: bool = True, refresh: bool = False, revision: str | None = None, **kwargs)
```

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

**Parâmetros:**

path (`str`) : Caminho para o diretório.

detail (`bool`, *opcional*) : Se True, retorna uma lista de dicionários contendo informações dos arquivos. Se False, retorna uma lista de caminhos de arquivos. O padrão é True.

refresh (`bool`, *opcional*) : Se True, ignora o cache e busca os dados mais recentes. O padrão é False.

revision (`str`, *opcional*) : A revisão git a ser listada.

**Retorna:** `list[Union[str, dict[str, Any]]]`

Lista de caminhos de arquivo (se detail=False) ou lista de dicionários de informações de arquivo (se detail=True).

Liste o conteúdo de um diretório.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.ls).

> [!WARNING]
> Observação: Sempre que possível, use `HfApi.list_repo_tree()` para melhor desempenho.

#### modificado[[huggingface_hub.HfFileSystem.modified]]

```python
modified(path: str, **kwargs)
```

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

**Parâmetros:**

path (`str`) : Caminho para o arquivo.

**Retorna:** `datetime`

Hora da última modificação do arquivo.

Obtenha a data e a hora da última modificação de um arquivo.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.modified).

#### resolve_path[[huggingface_hub.HfFileSystem.resolve_path]]

```python
resolve_path(path: str, revision: str | None = None)
```

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

**Parâmetros:**

path (`str`) : Caminho a ser resolvido.

revision (`str`, *opcional*) : A revisão do repositório a ser resolvida. O padrão é a revisão especificada no caminho.

**Retorna:** `HfFileSystemResolvedPath`

Informações do caminho resolvido contendo `repo_type`, `repo_id`, `revision` e `path_in_repo`.

**Exceções:** ``ValueError`` ou ``NotImplementedError``

- ``ValueError`` -- Se o path contiver informações de revisão conflitantes.
- ``NotImplementedError`` -- Se tentar listar repositórios.

Resolve um caminho de sistema de arquivos do Hugging Face em seus componentes.

#### rm[[huggingface_hub.HfFileSystem.rm]]

```python
rm(path: str, recursive: bool = False, maxdepth: int | None = None, revision: str | None = None, **kwargs)
```

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

**Parâmetros:**

path (`str`) : Caminho a ser excluído.

recursive (`bool`, *opcional*) : Se True, exclui o diretório e todo o seu conteúdo. O padrão é False.

maxdepth (`int`, *opcional*) : Número máximo de subdiretórios a serem visitados ao excluir recursivamente.

revision (`str`, *opcional*) : A revisão do git a partir da qual excluir.

Excluir arquivos de um repositório.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.rm).

> [!WARNING]
> Nota: Sempre que possível, use `HfApi.delete_file()` para melhor desempenho.

#### url[[huggingface_hub.HfFileSystem.url]]

```python
url(path: str)
```

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

**Parâmetros:**

path (`str`) : Caminho para obter a URL.

**Retorna:** `str`

URL HTTP para acessar o arquivo ou diretório no Hub.

Obtenha a URL HTTP do caminho fornecido.

#### walk[[huggingface_hub.HfFileSystem.walk]]

```python
walk(path: str, *args, **kwargs)
```

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

**Parâmetros:**

path (`str`) : Caminho raiz para listar os arquivos.

**Retorna:** `Iterator[tuple[str, list[str], list[str]]]`

Um iterador de tuplas (caminho, lista de nomes de diretórios, lista de nomes de arquivos).

Retorna todos os arquivos abaixo do caminho especificado.

Para mais detalhes, consulte a [documentação do fsspec](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem.walk).