pathlib.Path.info é um recurso moderno da biblioteca padrão que ajuda a consultar informações sobre arquivos e diretórios com menos chamadas repetidas ao sistema operacional. Ele é especialmente útil em rotinas que percorrem muitas entradas, classificam caminhos, filtram tipos de arquivo ou constroem inventários de diretórios.
Neste guia, você vai entender o objetivo de Path.info, como ele se relaciona com métodos tradicionais como is_file(), is_dir() e exists(), quando o cache pode melhorar o desempenho e quais cuidados evitam resultados desatualizados.
Para revisar conceitos relacionados, consulte também nossos artigos sobre pathlib no Python, módulo os, shutil no Python e glob no Python.
O que é pathlib.Path.info
Path.info fornece um objeto associado a um caminho que expõe consultas sobre o tipo da entrada. A ideia central é permitir que informações obtidas durante a enumeração de diretórios sejam reaproveitadas, reduzindo chamadas adicionais ao sistema.
Em muitos sistemas, descobrir se um caminho é arquivo, diretório ou link simbólico exige uma consulta de metadados. Quando isso é repetido para milhares de entradas, o custo acumulado pode ser relevante. O objeto de informações funciona como uma camada de acesso que pode aproveitar dados já disponíveis.
Por que esse recurso foi adicionado
Ao percorrer diretórios, APIs do sistema frequentemente já retornam parte dos metadados de cada entrada. Métodos tradicionais de Path podem fazer novas consultas mesmo quando essas informações acabaram de ser obtidas. Path.info foi projetado para reduzir essa duplicação em cenários apropriados.
Isso não significa que todo programa ficará automaticamente mais rápido. O ganho aparece principalmente em varreduras grandes, sistemas de arquivos remotos, discos lentos, diretórios com muitas entradas ou aplicações que executam várias verificações de tipo para o mesmo caminho.
Exemplo básico
from pathlib import Path
pasta = Path("dados")
for caminho in pasta.iterdir():
info = caminho.info
if info.is_file():
print("arquivo:", caminho.name)
elif info.is_dir():
print("diretório:", caminho.name)
O exemplo classifica as entradas sem misturar strings de caminhos com funções procedurais. A API permanece orientada a objetos e integrada ao restante do pathlib.
Diferença para is_file e is_dir
Os métodos caminho.is_file() e caminho.is_dir() continuam válidos e simples. Eles consultam o estado atual do caminho no momento da chamada. Já as informações acessadas por caminho.info podem aproveitar um cache associado ao objeto.
Essa diferença é importante. Quando você precisa da visão mais recente possível após alterações no sistema de arquivos, os métodos diretos podem ser mais apropriados. Quando está classificando entradas de uma enumeração estável, o objeto de informações pode evitar trabalho redundante.
Cache e consistência
O cache melhora desempenho, mas cria uma janela em que o estado armazenado pode não refletir alterações recentes. Um arquivo pode ser removido, substituído ou transformado em diretório depois que a informação foi obtida.
Não trate o cache como garantia permanente. Em fluxos críticos, valide novamente imediatamente antes de abrir, remover, mover ou sobrescrever um caminho. O sistema de arquivos pode mudar entre a verificação e a operação, inclusive por outro processo.
Como obter informações atualizadas
Quando você precisa descartar informações antigas, crie um novo objeto Path para o mesmo caminho ou use os métodos de consulta direta. O ponto principal é não presumir que um objeto mantido por muito tempo representa o estado atual.
from pathlib import Path
caminho = Path("relatorio.csv")
# Consulta associada ao objeto atual
if caminho.info.is_file():
print("Era um arquivo na consulta armazenada")
# Novo objeto para uma nova observação
atual = Path(caminho)
if atual.is_file():
print("Ainda é um arquivo")
Links simbólicos
Links simbólicos exigem atenção porque existe diferença entre consultar o link e consultar o destino. Uma verificação pode seguir o link e classificar o alvo como arquivo ou diretório, enquanto outra pode testar especificamente se a entrada é um link.
Defina claramente o comportamento desejado. Em ferramentas de backup, sincronização e limpeza, seguir links sem controle pode levar a ciclos, acesso fora da árvore esperada ou remoção de destinos indevidos.
Diretórios muito grandes
Em diretórios com dezenas de milhares de itens, pequenas diferenças por entrada se acumulam. Evitar uma chamada de metadados por caminho pode reduzir a latência total e o uso de recursos.
Ainda assim, meça com dados reais. O desempenho varia por sistema operacional, tipo de disco, cache do kernel, rede e características do diretório. Use timeit ou medições de aplicação em vez de depender apenas de expectativas teóricas.
Exemplo de inventário
from pathlib import Path
def inventariar(raiz: Path) -> dict[str, int]:
resultado = {"arquivos": 0, "diretorios": 0, "links": 0, "outros": 0}
for caminho in raiz.iterdir():
info = caminho.info
if info.is_symlink():
resultado["links"] += 1
elif info.is_file():
resultado["arquivos"] += 1
elif info.is_dir():
resultado["diretorios"] += 1
else:
resultado["outros"] += 1
return resultado
print(inventariar(Path(".")))
Esse padrão é útil em painéis administrativos, verificadores de conteúdo, indexadores e ferramentas de migração.
Tratamento de erros
Permissões, caminhos removidos, unidades desconectadas e erros de rede podem interromper consultas. Envolva operações relevantes em try e trate exceções específicas, como PermissionError e FileNotFoundError.
from pathlib import Path
for caminho in Path("/dados").iterdir():
try:
if caminho.info.is_file():
processar(caminho)
except PermissionError:
registrar("sem permissão", caminho)
except FileNotFoundError:
registrar("entrada removida", caminho)
Evite capturar Exception sem registrar contexto. O nome do caminho, a operação e o tipo de erro são essenciais para diagnóstico.
Condições de corrida
Verificar e depois agir não é uma operação atômica. Um caminho considerado arquivo pode mudar antes da abertura. Por isso, prefira executar a operação e tratar a falha quando segurança e consistência forem importantes.
Por exemplo, em vez de confiar apenas em is_file(), tente abrir o arquivo no modo correto e trate a exceção. A verificação preliminar pode melhorar mensagens ou filtros, mas não substitui a validação da operação real.
Uso em aplicações web
Em uploads e gerenciadores de arquivos, nunca use apenas o tipo da entrada para validar conteúdo. Verifique extensão, tamanho, MIME, permissões e, quando necessário, assinatura binária. Um caminho ser arquivo regular não significa que seu conteúdo seja seguro.
Também normalize e restrinja caminhos para impedir travessia de diretórios. Resolva a raiz permitida e confirme que o destino permanece dentro dela antes de ler ou gravar.
Compatibilidade de versão
Path.info depende de uma versão recente do Python. Bibliotecas que oferecem suporte a versões anteriores devem detectar a disponibilidade ou manter um caminho alternativo com métodos tradicionais.
def eh_arquivo(caminho):
info = getattr(caminho, "info", None)
if info is not None:
return info.is_file()
return caminho.is_file()
Consulte a documentação oficial do pathlib para confirmar a API da versão utilizada. Para detalhes de evolução e decisões da linguagem, acompanhe também as notas oficiais What’s New.
Boas práticas
Use Path.info em varreduras locais e curtas. Evite manter objetos por longos períodos quando o diretório muda constantemente. Trate erros por entrada para que um único problema não interrompa todo o lote. Não use o cache como autorização de segurança. Meça o desempenho antes e depois.
Também mantenha as operações legíveis. Uma otimização que economiza pouco, mas torna o fluxo difícil de entender, pode não compensar. Comece com Path tradicional e adote o objeto de informações nos pontos comprovadamente críticos.
Quando usar
O recurso é indicado para indexadores, analisadores de diretórios, ferramentas de backup, pipelines de dados, sistemas de sincronização e aplicações que precisam classificar muitas entradas. Ele é menos relevante para scripts que verificam apenas alguns caminhos.
Conclusão
pathlib.Path.info oferece uma forma eficiente e integrada de consultar características de caminhos, especialmente durante enumerações de diretórios. Seu principal benefício é reaproveitar informações e reduzir consultas repetidas ao sistema operacional.
O uso correto exige compreender cache, mudanças concorrentes, links simbólicos e compatibilidade de versão. Com medições reais e validação antes de operações críticas, o recurso pode melhorar desempenho sem sacrificar clareza ou segurança.
