🐍 Python + Claude Code

Antes de pedirle cualquier cosa a Claude Code en Python, necesitas tener un Python funcional. La forma más confiable es usar pyenv para gestionar versiones o el python3 nativo del sistema. pyenv permite tener varias versiones en paralelo y cambiar entre ellas según el proyecto.

Claude Code puede detectar qué versión de Python está activa y adaptar el código generado. Pero si no tienes una configuración limpia, generará código para una versión que quizá no exista en tu máquina. Empieza bien.

# 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

Un entorno virtual es una copia aislada de Python para cada proyecto. Sin ella, los paquetes de distintos proyectos entran en conflicto. El venv viene con Python; el uv es una alternativa moderna y mucho más rápida.

# 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

Cuando Claude Code genera código que usa requests, fastapi o cualquier otro paquete, tienes que instalarlo. El pip es el gestor predeterminado; uv pip hace lo mismo entre 10 y 100 veces más rápido. El archivo requirements.txt registra exactamente lo que se instaló.

# 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

El flujo clásico con Claude Code: describes lo que quieres automatizar, genera el script, lo ejecutas y lo ajustas. Empieza con scripts pequeños que hagan UNA cosa bien. Usa argparse para argumentos, pathlib para rutas y if __name__ == "__main__" como punto 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)

Cuando falla un script, pega el traceback completo en Claude Code. Identifica el error, sugiere la solución y puede aplicarla directamente. Para bugs más sutiles, usa pdb (el depurador nativo) o breakpoint() para pausar la ejecución e inspeccionar variables.

Python es dinámico, pero type hints hacen que el código sea más seguro y más fácil de entender para la IA. Pídele a Claude Code que agregue type hints a tu código existente: "adicione type hints a todas as funcoes deste modulo". Usa 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}")
    }