PurePath.full_match é um método do módulo pathlib criado para verificar se um caminho inteiro corresponde a um padrão no estilo glob. Ele é especialmente útil quando você precisa validar nomes de arquivos, estruturas de diretórios, extensões ou caminhos relativos sem acessar o sistema de arquivos. Diferentemente de operações que testam apenas uma parte do texto, full_match considera o caminho completo, o que reduz resultados inesperados e torna regras de filtragem mais claras.
Neste guia, você vai entender como o método funciona, como ele se compara a match, quais padrões aceita, como lidar com diferenças entre sistemas operacionais e como aplicá-lo em validadores, ferramentas de linha de comando e pipelines de automação.
O que é PurePath.full_match
PurePath representa caminhos de forma puramente lógica. Isso significa que ele permite analisar e manipular caminhos sem consultar se arquivos ou pastas realmente existem. Essa separação é importante em testes, parsers, aplicações web e sistemas que recebem caminhos vindos de usuários ou APIs.
from pathlib import PurePath
caminho = PurePath("dados/2026/relatorio.csv")
print(caminho.full_match("dados/**/*.csv"))
O resultado é verdadeiro porque o padrão descreve todo o caminho: ele começa em dados, aceita diretórios intermediários e termina com um arquivo CSV. O método retorna apenas um booleano, sem abrir arquivos nem percorrer diretórios.
Por que usar correspondência completa
Filtros de caminho costumam falhar quando verificam apenas sufixos ou trechos isolados. Uma regra como endswith('.csv') confirma a extensão, mas não garante que o arquivo esteja dentro da pasta correta. Já uma expressão regular pode resolver o problema, porém exige mais código e cuidados com separadores.
Com full_match, a regra fica próxima da forma como as pessoas descrevem arquivos:
from pathlib import PurePath
permitidos = [
PurePath("entrada/clientes.csv"),
PurePath("entrada/2026/vendas.csv"),
PurePath("backup/vendas.csv"),
]
for item in permitidos:
if item.full_match("entrada/**/*.csv"):
print("aceito:", item)
Somente caminhos que combinam com toda a estrutura definida são aceitos. Isso melhora a segurança de rotinas que importam arquivos, processam anexos ou montam listas de artefatos.
Padrões glob essenciais
Os padrões seguem a linguagem glob usada pelo pathlib. O asterisco simples corresponde a caracteres dentro de uma parte do caminho; o ponto de interrogação corresponde a um único caractere; classes entre colchetes representam conjuntos; e o duplo asterisco permite atravessar níveis de diretório.
from pathlib import PurePath
exemplos = [
("logs/app.log", "logs/*.log"),
("img/foto1.png", "img/foto?.png"),
("dados/a.csv", "dados/[ab].csv"),
("src/pkg/modulo.py", "src/**/*.py"),
]
for valor, padrao in exemplos:
print(valor, PurePath(valor).full_match(padrao))
O principal benefício é expressar a intenção sem transformar o caminho em uma string manualmente. O próprio objeto entende componentes, separadores e regras da família de caminhos utilizada.
Diferença entre full_match e match
PurePath.match é útil, mas possui uma semântica histórica que pode considerar padrões relativos a partir do lado direito do caminho. Isso é conveniente em alguns filtros, porém pode surpreender quando a exigência é validar a estrutura inteira. full_match deixa essa intenção explícita.
from pathlib import PurePath
p = PurePath("projeto/src/app.py")
print(p.match("src/*.py"))
print(p.full_match("src/*.py"))
print(p.full_match("projeto/src/*.py"))
Em validações de entrada, prefira full_match quando o padrão deve representar todo o valor recebido. Use match quando o objetivo for uma regra mais flexível ou compatível com código antigo.
Controle de maiúsculas e minúsculas
O método aceita o parâmetro case_sensitive. Quando ele não é informado, o comportamento padrão segue a família de caminho. Caminhos POSIX normalmente diferenciam letras maiúsculas de minúsculas; caminhos Windows normalmente não diferenciam.
from pathlib import PurePosixPath
arquivo = PurePosixPath("Imagens/Foto.PNG")
print(arquivo.full_match("imagens/*.png"))
print(arquivo.full_match("imagens/*.png", case_sensitive=False))
Definir o parâmetro explicitamente é uma boa prática em regras de negócio que precisam produzir o mesmo resultado em qualquer plataforma. Assim, testes executados no Linux e no Windows não divergem silenciosamente.
PurePosixPath e PureWindowsPath
Você pode escolher a semântica do caminho sem depender do sistema operacional atual. PurePosixPath entende caminhos com barras normais, enquanto PureWindowsPath entende unidades, barras invertidas e convenções do Windows.
from pathlib import PurePosixPath, PureWindowsPath
web = PurePosixPath("assets/css/site.css")
win = PureWindowsPath(r"C:\Projetos\app\main.py")
print(web.full_match("assets/**/*.css"))
print(win.full_match(r"C:\Projetos\**\*.py"))
Essa possibilidade é valiosa em aplicações que processam manifests, arquivos compactados, repositórios remotos ou configurações de outras máquinas.
Validação de uploads
Um uso comum é validar o nome lógico de um upload antes de salvá-lo. A correspondência de caminho não substitui verificações de MIME, tamanho e conteúdo, mas adiciona uma camada útil para restringir diretórios e extensões esperadas.
from pathlib import PurePosixPath
PADRAO = "uploads/**/*.csv"
def caminho_permitido(valor: str) -> bool:
caminho = PurePosixPath(valor)
return caminho.full_match(PADRAO, case_sensitive=False)
entradas = [
"uploads/clientes/lista.csv",
"uploads/clientes/lista.exe",
"temporarios/lista.csv",
]
for entrada in entradas:
print(entrada, caminho_permitido(entrada))
Antes de aceitar caminhos fornecidos por usuários, também normalize a lógica da aplicação e rejeite componentes suspeitos, como segmentos de navegação para o diretório pai. Para aprender mais sobre caminhos modernos, veja o artigo sobre pathlib.Path.walk no Python.
Filtros em pipelines
Em pipelines de dados, você pode aplicar vários padrões para separar arquivos por função:
from pathlib import PurePath
REGRAS = {
"entrada": "data/incoming/**/*.json",
"processado": "data/processed/**/*.parquet",
"log": "logs/**/*.log",
}
def classificar(valor: str) -> str | None:
caminho = PurePath(valor)
for nome, padrao in REGRAS.items():
if caminho.full_match(padrao, case_sensitive=False):
return nome
return None
Essa abordagem mantém padrões centralizados e fáceis de revisar. Ela combina bem com automações descritas no artigo sobre os.fwalk no Python e com empacotamento apresentado em zipapp no Python.
Erros comuns
O primeiro erro é esquecer que a correspondência é completa. Um padrão *.py não descreve necessariamente um caminho com vários diretórios. Quando existirem níveis intermediários, use uma estrutura como **/*.py ou inclua explicitamente o prefixo.
O segundo erro é misturar separadores e famílias de caminho. Quando estiver analisando caminhos de outra plataforma, use PureWindowsPath ou PurePosixPath diretamente.
O terceiro erro é tratar glob como uma garantia de segurança. O padrão valida a forma do caminho, não o conteúdo real do arquivo. Combine-o com controles de acesso, resolução segura do destino e validação de dados.
Testes automatizados
Como PurePath não toca o sistema de arquivos, os testes são rápidos e determinísticos:
from pathlib import PurePosixPath
def permitido(valor: str) -> bool:
return PurePosixPath(valor).full_match(
"relatorios/**/*.csv",
case_sensitive=False,
)
def test_relatorio_valido():
assert permitido("relatorios/2026/janeiro.csv")
def test_extensao_invalida():
assert not permitido("relatorios/2026/janeiro.exe")
def test_pasta_invalida():
assert not permitido("privado/janeiro.csv")
Você pode integrar essas regras a modelos, parsers e contratos tipados. O conteúdo sobre typing.override no Python mostra como fortalecer contratos em hierarquias, enquanto dataclasses.KW_ONLY no Python ajuda a criar APIs mais explícitas.
Compatibilidade de versão
Antes de usar o método em produção, confirme a versão mínima do Python definida pelo projeto. Recursos recentes podem não existir em ambientes antigos. Quando precisar manter compatibilidade, encapsule a chamada em uma função e forneça uma alternativa testada.
from pathlib import PurePath
def corresponde(caminho: str, padrao: str) -> bool:
objeto = PurePath(caminho)
metodo = getattr(objeto, "full_match", None)
if metodo is None:
raise RuntimeError("A versão atual do Python não oferece full_match")
return metodo(padrao)
A documentação oficial de pathlib deve ser a referência principal para detalhes de versão. Para entender a linguagem de padrões, consulte também a documentação do módulo fnmatch.
Conclusão
PurePath.full_match oferece uma maneira direta e legível de verificar se um caminho inteiro corresponde a um padrão glob. Ele evita comparações frágeis com strings, funciona sem acesso ao disco e permite controlar explicitamente a sensibilidade a maiúsculas.
Use o método para validar caminhos lógicos, classificar arquivos, filtrar artefatos e testar regras multiplataforma. Mantenha os padrões específicos, escolha a família de caminho correta e combine a correspondência com outras validações quando houver entrada não confiável.
