pycomprepair 0.1.1

Semantic upgrade assistant and compatibility codemods for Python dependencies.

PyCompatRepair (pycomprepair)

Asistente de upgrades semánticos y codemods de compatibilidad para dependencias Python.

pycomprepair analiza el código de tu proyecto frente a una versión actual y una versión objetivo de una librería, detecta call-sites incompatibles y aplica codemods verificables con --dry-run, diff legible y posibilidad de rollback.

A diferencia de herramientas como pyupgrade (solo sintaxis del lenguaje) o bump-pydantic (solo Pydantic v1→v2), pycomprepair está pensado como un núcleo extensible con un sistema de plugins por ecosistema. El MVP incluye:

• Núcleo: extracción de firmas con griffe, detección de incompatibilidades, motor de codemods sobre libcst.
• Plugin Pydantic v2: BaseSettings, Config → model_config, @validator → @field_validator, .dict() → .model_dump(), .parse_obj() → .model_validate(), etc.
• Plugin FastAPI: deprecated on_event → lifespan, Depends con use_cache deprecated, etc.
• Plugin SQLAlchemy 2.0: from sqlalchemy.ext.declarative import declarative_base → sqlalchemy.orm, session.query(M).get(pk) → session.get(M, pk), avisos sobre declarative_base() y Query.update/delete.
• Plugin Django 5.0: smart_text/force_text → smart_str/force_str, ugettext* → gettext*, aviso sobre django.utils.timezone.utc y Meta.index_together.
• CLI (pycomprepair) con scan, repair, report.

Instalación

pip install pycomprepair

o, si usas uv:

uv pip install pycomprepair

Requiere Python 3.10+.

Para desarrollo local sobre el repositorio:

uv venv
uv pip install -e ".[dev]"

Uso rápido

# Escanear el proyecto y detectar incompatibilidades
pycomprepair scan ./src --target "pydantic>=2.0,<3.0"

# Aplicar codemods en modo dry-run (muestra diff, no escribe)
pycomprepair repair ./src --target "pydantic>=2.0,<3.0" --dry-run

# Aplicar de verdad
pycomprepair repair ./src --target "pydantic>=2.0,<3.0"

# Generar reporte HTML/Markdown
pycomprepair report ./src --target "pydantic>=2.0,<3.0" --format markdown

Configuración por proyecto

Para evitar repetir --target y demás flags en cada llamada, PyCompatRepair lee configuración de un fichero pycomprepair.toml (o de una sección [tool.pycomprepair] en tu pyproject.toml). La búsqueda sube por los directorios padre desde la ruta que pases en la CLI, así que puedes ponerlo en la raíz del repo:

# pycomprepair.toml
target = "pydantic>=2.0,<3.0"
min_confidence = 0.8
unsafe_fixes = false
ignore = ["PYD002", "DJA004"]  # códigos de regla que no quieres ver

Equivalente dentro de pyproject.toml:

[tool.pycomprepair]
target = "pydantic>=2.0,<3.0"
ignore = ["PYD002"]

Los flags de la CLI tienen prioridad sobre la configuración, y la configuración sobre los valores por defecto. Con esto, pycomprepair scan ./src ya basta una vez configurado el proyecto.

Descubrimiento dinámico (discover)

Más allá de los plugins manuales, pycomprepair puede consultar la API real de un paquete instalado mediante griffe y avisarte de imports que ya no existen en esa versión. Es la forma más rápida de auditar tu código frente al venv objetivo:

# Crea un venv con la versión a la que quieres migrar
uv pip install "django==5.0.*"

# Encuentra imports rotos respecto a la Django instalada
pycomprepair discover ./src --package django

Cada importación cuyo símbolo no figura en la API cargada genera un issue DSC001. Esto cubre renombrados y eliminaciones que aún no están reflejados en los plugins escritos a mano y sirve como red de seguridad genérica.

Úsalo como GitHub Action

PyCompatRepair se distribuye también como composite action, así que puedes añadir un job de compatibilidad a cualquier repositorio Python en cinco líneas:

# .github/workflows/pycomprepair.yml
name: Compatibility check
on: [pull_request]
permissions:
  contents: read
  pull-requests: write  # solo si activas comment-on-pr

jobs:
  pycomprepair:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: alvaroo-fdez/pycomprepair@main
        with:
          path: src
          target: "pydantic>=2.0,<3.0"
          mode: scan            # "scan" (default) o "repair"
          fail-on-issues: "true"
          comment-on-pr: "true" # publica/actualiza un comentario idempotente

Inputs principales:

Input	Default	Descripción
path	.	Ruta a escanear/reparar.
target	—	Requisito objetivo, p.ej. "pydantic>=2.0,<3.0".
mode	scan	scan solo detecta; repair además incluye diffs en el reporte.
fail-on-issues	true	Falla el job si se detectan incompatibilidades.
comment-on-pr	false	Publica/actualiza un comentario en el PR con el reporte (idempotente).
version	—	Especificador opcional, p.ej. ==0.1.0 para fijar versión.
git-ref	—	Instala desde un ref del repo (útil para probar cambios sin publicar).
skip-install	false	Salta la instalación si ya tienes pycomprepair en el PATH.

El reporte siempre se publica en el step summary del job; los outputs issues-count y report-path quedan disponibles para pasos posteriores.

Arquitectura

src/pycomprepair/
├── core/           # Diff de firmas, registro de plugins, modelos de issue
├── codemods/       # Helpers libcst reutilizables
├── plugins/        # Plugins por ecosistema (pydantic, fastapi, ...)
├── report/         # Renderers Markdown/HTML
└── cli.py          # CLI Typer

Licencia

Apache-2.0. Ver LICENSE.