🐍 Python + Claude Code

Antes de pedir qualquer coisa ao Claude Code em Python, voce precisa de um Python funcional. A forma mais confiavel e usar pyenv para gerenciar versoes ou o python3 nativo do sistema. O pyenv permite ter multiplas versoes lado a lado e trocar entre elas por projeto.

Claude Code consegue detectar qual versao de Python esta ativa e adaptar o codigo gerado. Mas se voce nao tem um setup limpo, ele vai gerar codigo para uma versao que talvez nao exista na sua maquina. Comece certo.

# Instalar pyenv (macOS/Linux)
curl https://pyenv.run | bash

# Instalar Python 3.12
pyenv install 3.12

# Definir como versao do projeto
cd meu-projeto
pyenv local 3.12

# Verificar
python --version   # Python 3.12.x

Um virtual environment e uma copia isolada do Python para cada projeto. Sem ele, pacotes de projetos diferentes colidem. O venv vem com Python; o uv e uma alternativa moderna e muito mais rapida.

# Opcao 1: venv padrao
python3 -m venv .venv
source .venv/bin/activate

# Opcao 2: uv (rapido)
pip install uv
uv venv .venv
source .venv/bin/activate

# Verificar que esta no venv
which python  # deve apontar para .venv/bin/python

Quando Claude Code gera codigo que usa requests, fastapi ou qualquer outro pacote, voce precisa instala-lo. O pip e o gerenciador padrao; uv pip faz a mesma coisa 10-100x mais rapido. O arquivo requirements.txt registra exatamente o que foi instalado.

# Instalar um pacote
pip install requests

# Travar dependencias
pip freeze > requirements.txt

# Instalar de um requirements.txt
pip install -r requirements.txt

# Alternativa rapida com uv
uv pip install -r requirements.txt

O fluxo classico com Claude Code: voce descreve o que quer automatizar, ele gera o script, voce roda e ajusta. Comece com scripts pequenos que fazem UMA coisa bem. Use argparse para argumentos, pathlib para caminhos e if __name__ == "__main__" como ponto de entrada.

#!/usr/bin/env python3
"""Organiza arquivos por extensao em subpastas."""
import argparse
from pathlib import Path

def organize(directory: Path) -> None:
    for f in directory.iterdir():
        if f.is_file() and not f.name.startswith('.'):
            ext_dir = directory / f.suffix.lstrip('.')
            ext_dir.mkdir(exist_ok=True)
            f.rename(ext_dir / f.name)
            print(f"  {f.name} -> {ext_dir.name}/")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("dir", type=Path)
    args = parser.parse_args()
    organize(args.dir)

Quando um script falha, cole o traceback inteiro no Claude Code. Ele identifica o erro, sugere o fix e pode aplicar direto. Para bugs mais sutis, use pdb (o debugger nativo) ou breakpoint() para pausar a execucao e inspecionar variaveis.

Python e dinamico, mas type hints tornam o codigo mais seguro e mais facil para a IA entender. Peca ao Claude Code para adicionar type hints ao seu codigo existente: "adicione type hints a todas as funcoes deste modulo". Use mypy para verificar.

from pathlib import Path

def count_lines(filepath: Path) -> int:
    """Conta linhas de um arquivo."""
    return len(filepath.read_text().splitlines())

def process_files(directory: Path, ext: str = ".py") -> dict[str, int]:
    """Retorna {arquivo: n_linhas} para cada arquivo com a extensao."""
    return {
        f.name: count_lines(f)
        for f in directory.glob(f"*{ext}")
    }