pathlib & os
pathlib fornece caminhos orientados a objetos (Path) para juntar, ler, glob e mkdir. os e os.path permanecem para flags de baixo nível, variáveis de ambiente e IDs de processo - combine ambos em código de produção.
Receita
from pathlib import Path
root = Path(__file__).resolve().parent
config = root / "config" / "app.toml"
config.parent.mkdir(parents=True, exist_ok=True)
config.write_text("key = 'value'\n", encoding="utf-8")Quando usar isso:
- Construindo caminhos de arquivo portáteis
- Percorrendo diretórios com
glob/rglob - Lendo/escrevendo arquivos de texto ou binários
- Verificando existência e metadados de arquivos
- Ambiente e cwd via
os.environ,os.getcwd
Exemplo de Trabalho
import os
from pathlib import Path
def find_py_files(src: Path, limit: int = 5) -> list[Path]:
return sorted(src.rglob("*.py"))[:limit]
def ensure_cache() -> Path:
cache = Path(os.environ.get("APP_CACHE", Path.home() / ".cache" / "demo"))
cache.mkdir(parents=True, exist_ok=True)
return cache
root = Path.cwd()
print("cwd", root)
print("arquivos de exemplo", find_py_files(root))
stamp = ensure_cache() / "last.run"
stamp.write_text("ok", encoding="utf-8")
print(stamp.read_text(encoding="utf-8"))O que isso demonstra:
- O operador
/junta segmentos de caminho de forma portátil rglobbusca recursivamente a partir da raizmkdir(parents=True, exist_ok=True)cria a árvore- Padrão de substituição de ambiente para diretórios configuráveis
Mergulho Profundo
pathlib vs os.path
| Tarefa | pathlib | os |
|---|---|---|
| Juntar | base / "x" | os.path.join |
| Existe | p.exists() | os.path.exists |
| Ambiente | - | os.environ |
| chmod | p.chmod | os.chmod |
Texto vs Binário
read_text/write_textprecisam de codificaçãoread_bytespara imagens, pickles, arquivos
Armadilhas
- Concatenação de caminhos de string - quebra no Windows. Correção: Objetos Path.
- Caminhos relativos sem âncora - dependem de surpresas do cwd. Correção:
resolve()ou passe o diretório base. - glob em árvores enormes - início frio lento. Correção: estreite a raiz, use a poda de
os.walkou um índice dedicado. - Corrida TOCTOU - existe e depois abre falha. Correção: abra EAFP ou tente/exceto.
- Codificação ausente - mojibake no Windows. Correção: sempre utf-8 para texto, a menos que o local seja conhecido.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| os.walk | Poda detalhada | Glob simples suficiente |
| módulo tempfile | Arquivos temporários seguros | Diretório de cache fixo |
| shutil | Copiar/mover árvore | Pathlib de arquivo único |
FAQs
Path vs str para APIs?
Aceite os.PathLike (Path | str) em funções públicas; converta internamente para Path.
Absoluto vs resolve?
resolve() segue links simbólicos e torna absoluto - use antes de comparar caminhos.
Diretório home?
Path.home() ou ~ expandido via expanduser().
Excluir árvore?
shutil.rmtree - pathlib não tem exclusão recursiva até unlink/rmdir cuidadoso.
Observar sistema de arquivos?
Nenhum observador ótimo na biblioteca padrão - watchdog PyPI em algumas plataformas; polling glob para casos simples.
Mutação de os.environ?
Afeta processos filhos - documente efeitos colaterais em ferramentas de CLI.
Links simbólicos?
is_symlink, readlink, comportamento de resolve - conheça o sistema de arquivos de implantação.
Pathlib thread-safe?
Objetos Path imutáveis; o próprio sistema de arquivos pode ter corridas - o mesmo que os.
Caminhos Unicode?
Caminhos do Python 3 são str (unicode) - ainda observe a normalização NFC no macOS.
Django MEDIA_ROOT?
Configure como caminho str; use Path em novo código dentro do Django para consistência.
Relacionado
- subprocess - execute comandos com caminhos
- json & Serialization - leia arquivos de configuração
- Visão Geral da Biblioteca Padrão - mapa
- Arquivos e I/O - fundamentos
Versões do Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.