pathlib.Path.info no Python oferece uma forma eficiente de consultar informações sobre um caminho, como saber se ele representa um arquivo, diretório, link simbólico ou outro tipo de entrada. O recurso é especialmente útil em varreduras de diretórios, indexadores, ferramentas de backup, analisadores de projetos, pipelines de dados e aplicações que precisam classificar muitos caminhos sem repetir chamadas caras ao sistema operacional.
A principal ideia é simples: em vez de perguntar várias vezes ao sistema se um caminho é arquivo, diretório ou link, você pode usar um objeto de informações associado ao Path. Quando esse objeto já possui dados obtidos durante uma iteração, ele pode reaproveitá-los e reduzir trabalho desnecessário. Isso torna o código mais claro e, em cenários com muitos arquivos, potencialmente mais rápido.
O que é pathlib.Path.info
Path.info representa um conjunto de consultas sobre o tipo e a existência de um caminho. Ele foi pensado para trabalhar de forma integrada com objetos pathlib.Path, mantendo a API orientada a objetos da biblioteca padrão. Em vez de combinar chamadas soltas de os.path, os.stat e verificações manuais, você centraliza a lógica em um objeto ligado ao caminho.
O valor real aparece quando você percorre um diretório. Em muitas plataformas, a iteração já recebe do sistema operacional metadados básicos sobre cada entrada. O Python pode aproveitar essas informações e evitar uma nova consulta para cada teste de tipo. Isso não elimina todas as chamadas de sistema, mas reduz repetições quando os dados já estão disponíveis.
Exemplo básico
from pathlib import Path
caminho = Path("dados/relatorio.csv")
if caminho.info.exists():
if caminho.info.is_file():
print("É um arquivo")
elif caminho.info.is_dir():
print("É um diretório")
O exemplo consulta a existência e o tipo do caminho por meio de info. A sintaxe deixa explícito que você está perguntando sobre metadados do objeto. Para operações que realmente precisam abrir, ler ou escrever o arquivo, continue usando os métodos normais de Path.
Usando com iteração de diretórios
from pathlib import Path
raiz = Path("projeto")
for item in raiz.iterdir():
if item.info.is_dir():
print("Diretório:", item.name)
elif item.info.is_file():
print("Arquivo:", item.name)
elif item.info.is_symlink():
print("Link simbólico:", item.name)
Esse é um dos cenários mais naturais para Path.info. Ao percorrer centenas ou milhares de entradas, a diferença entre reutilizar informações e executar uma consulta completa para cada teste pode ser relevante, principalmente em discos de rede, volumes lentos, contêineres ou sistemas com alta latência.
Cache e validade das informações
As informações podem ser armazenadas em cache. Isso significa que uma resposta obtida anteriormente pode continuar sendo usada mesmo que o sistema de arquivos tenha mudado depois. Se outro processo criar, remover ou substituir o arquivo, o objeto já existente pode manter uma visão antiga.
Por isso, trate Path.info como uma fotografia conveniente do estado conhecido, não como uma garantia permanente. Quando você precisa confirmar o estado atual antes de uma operação crítica, crie um novo objeto Path ou use uma consulta que force uma nova leitura conforme a API disponível na versão utilizada.
from pathlib import Path
original = Path("entrada.txt")
print(original.info.exists())
# Depois de uma alteração externa, crie um novo Path
atualizado = Path(original)
print(atualizado.info.exists())
Essa distinção é importante em watchers, filas de processamento, sistemas de upload e tarefas concorrentes. Entre a verificação e a operação, o estado pode mudar. Esse fenômeno é conhecido como condição de corrida do tipo TOCTOU: time of check to time of use.
Não confunda verificação com autorização
Saber que um caminho existe ou é arquivo não significa que você possui permissão para abri-lo. O arquivo pode ser removido, ter suas permissões alteradas ou apontar para outro destino antes da leitura. Portanto, o código deve tratar exceções na operação real.
from pathlib import Path
arquivo = Path("config.toml")
if arquivo.info.is_file():
try:
conteudo = arquivo.read_text(encoding="utf-8")
except OSError as erro:
print("Não foi possível ler:", erro)
Essa prática evita depender apenas de verificações prévias. Em programas robustos, a tentativa de uso é a confirmação final.
Links simbólicos
Links simbólicos exigem atenção porque há duas perguntas diferentes: o caminho é um link e o destino do link é arquivo ou diretório? Dependendo do método usado, a consulta pode seguir o link ou examinar o próprio link. Leia a documentação da versão do Python que você utiliza e teste o comportamento desejado.
Em ferramentas de backup, sincronização e remoção, seguir links automaticamente pode causar problemas. Um link dentro de uma pasta pode apontar para fora da árvore esperada. Defina uma política explícita: ignorar links, copiar o link, ou seguir apenas quando o destino estiver dentro de uma raiz confiável.
Exemplo de inventário
from pathlib import Path
def inventariar(raiz: Path) -> dict[str, int]:
totais = {
"arquivos": 0,
"diretorios": 0,
"links": 0,
"outros": 0,
}
for item in raiz.iterdir():
if item.info.is_symlink():
totais["links"] += 1
elif item.info.is_file():
totais["arquivos"] += 1
elif item.info.is_dir():
totais["diretorios"] += 1
else:
totais["outros"] += 1
return totais
print(inventariar(Path("projeto")))
A função classifica apenas o primeiro nível. Para percorrer subdiretórios, você pode usar uma pilha, uma fila ou métodos recursivos. Em árvores muito grandes, prefira uma abordagem iterativa para controlar memória e profundidade.
Varredura recursiva segura
from pathlib import Path
def listar_arquivos(raiz: Path):
pendentes = [raiz]
while pendentes:
atual = pendentes.pop()
try:
itens = list(atual.iterdir())
except OSError:
continue
for item in itens:
if item.info.is_symlink():
continue
if item.info.is_dir():
pendentes.append(item)
elif item.info.is_file():
yield item
O exemplo evita seguir links e trata diretórios inacessíveis. Em aplicações reais, registre os erros, aplique limites e considere cancelamento. Um diretório pode conter milhões de entradas, e converter toda a iteração em lista pode consumir memória. Quando possível, processe cada entrada diretamente.
Desempenho e benchmarking
Não presuma que a otimização terá o mesmo efeito em todas as plataformas. Sistemas operacionais, formatos de disco, caches do kernel e implementações de diretório variam. Meça com dados semelhantes aos de produção.
from pathlib import Path
from time import perf_counter
raiz = Path("dataset")
inicio = perf_counter()
quantidade = sum(1 for p in raiz.iterdir() if p.info.is_file())
fim = perf_counter()
print(quantidade, fim - inicio)
Execute várias vezes, descarte aquecimentos e compare com uma versão equivalente. Um benchmark isolado em poucos arquivos pode medir mais ruído do que a diferença real.
Compatibilidade entre versões
Path.info é um recurso recente. Antes de usá-lo em uma biblioteca, confira a versão mínima do Python. Se o projeto precisa funcionar em versões anteriores, crie uma função compatível.
from pathlib import Path
def eh_arquivo(caminho: Path) -> bool:
info = getattr(caminho, "info", None)
if info is not None:
return info.is_file()
return caminho.is_file()
Essa estratégia mantém um único ponto de compatibilidade. Documente a versão mínima no pyproject.toml e teste a matriz no CI.
Integração com padrões de caminho
Você pode combinar a classificação com glob, rglob e filtros de nome. Para conhecer melhor essas ferramentas, consulte o artigo sobre pathlib no Python, o guia de glob no Python, o conteúdo sobre módulo os e o artigo de tratamento de erros.
from pathlib import Path
for item in Path("logs").glob("*.log"):
if item.info.is_file():
print(item)
O filtro por padrão reduz o conjunto analisado, mas não substitui a validação do tipo. Um nome terminado em .log ainda pode representar um link, diretório ou entrada especial.
Arquivos especiais
Em sistemas Unix, um caminho pode apontar para socket, FIFO, dispositivo de bloco ou dispositivo de caractere. Se sua aplicação espera apenas arquivos regulares, rejeite explicitamente outros tipos. Isso é importante em ferramentas que aceitam caminhos fornecidos pelo usuário.
Não abra indiscriminadamente entradas especiais. Ler um FIFO pode bloquear; acessar um dispositivo pode exigir privilégios; e um socket não deve ser tratado como arquivo comum.
Segurança com caminhos fornecidos pelo usuário
Path.info não impede path traversal. Antes de acessar arquivos recebidos por URL, formulário ou API, resolva a raiz permitida e confirme que o destino permanece dentro dela. Também evite confiar apenas em extensão.
from pathlib import Path
RAIZ = Path("uploads").resolve()
def caminho_seguro(nome: str) -> Path:
destino = (RAIZ / nome).resolve()
if RAIZ not in destino.parents and destino != RAIZ:
raise ValueError("Caminho fora da raiz permitida")
return destino
Depois da validação, ainda trate erros na abertura. Consulte a documentação oficial de pathlib e a referência de os para detalhes da plataforma.
Quando usar Path.info
Use quando você precisa classificar muitas entradas, especialmente após iterar diretórios. Também é adequado para gerar inventários, selecionar arquivos para processamento, ignorar diretórios, separar links e reduzir consultas repetidas.
Para uma única verificação simples, Path.is_file() ou Path.is_dir() continuam claros e suficientes. A escolha deve considerar legibilidade, compatibilidade e o perfil real de desempenho.
Erros comuns
Os erros mais comuns são confiar indefinidamente no cache, esquecer que o arquivo pode mudar após a verificação, seguir links sem política, ignorar exceções, assumir disponibilidade em versões antigas e usar benchmarks artificiais. Outro erro é tentar usar metadados como garantia de segurança.
Organize a lógica em funções pequenas. Uma função valida a raiz, outra classifica o tipo, outra executa a operação e trata falhas. Isso facilita testes e reduz decisões implícitas.
Conclusão
pathlib.Path.info melhora a classificação de caminhos ao reunir consultas de tipo e aproveitar informações já obtidas durante a iteração. Ele pode tornar varreduras mais eficientes e o código mais expressivo. Porém, o cache exige cuidado: sistemas de arquivos mudam, permissões variam e links podem apontar para locais inesperados. Combine o recurso com tratamento de exceções, validação de caminhos, política explícita de links, testes de compatibilidade e benchmarks realistas. Assim, você obtém desempenho sem comprometer correção e segurança.
