complexipy¶
Análisis ultrarrápido de complejidad cognitiva para Python, escrito en Rust.
Instalación • Inicio Rápido • Funcionalidades • Integraciones • Aprende Más • Complexipy Teams
Puntuando la complejidad cognitiva del código de Django (2.929 archivos). Puntos de referencia
Instalación¶
Git para las opciones de diff
Las opciones --diff, --diff-only y --staged requieren Git 2.30 o posterior
en tu PATH. Comprueba tu versión con git --version. Git no es necesario
para el análisis sin estas opciones.
¿Qué es la Complejidad Cognitiva?¶
La complejidad cognitiva mide qué tan difícil es seguir el flujo de control de una función. Úsala para mantener el código fácil de revisar y de cambiar, sin importar si lo escribió una persona o un agente de IA.
Estas dos funciones tienen la misma complejidad ciclomática, 4. Su complejidad cognitiva es diferente:
El código anidado obliga a quien lo lee a mantener más contexto, así que cada nivel de anidamiento suma a la puntuación. complexipy implementa para Python la métrica de Complejidad Cognitiva de G. Ann Campbell. Cómo se calculan las puntuaciones
Inicio Rápido¶
Línea de Comandos¶
# Analiza el directorio actual
complexipy .
# Establece un umbral personalizado
complexipy . --max-complexity-allowed 10
# Muestra las funciones que fallan con sugerencias de refactorización
complexipy . --failed --suggest-refactors
# Guarda los resultados en JSON
complexipy . --output-format json
# Bloquea regresiones contra una referencia de git
complexipy . --diff main
# Excluye rutas con patrones glob
complexipy . --exclude "tests/**"
API de Python¶
from complexipy import file_complexity
# Analiza un archivo
result = file_complexity("app.py")
print(f"File complexity: {result.complexity}")
for func in result.functions:
print(f"{func.name}: {func.complexity}")
Funcionalidades¶
-
Puntuaciones de complejidad cognitiva
Puntuaciones que siguen el artículo de G. Ann Campbell: anidamiento, interrupciones de flujo y secuencias booleanas.
-
Bloquea solo lo que un cambio empeora
--diffy--stagedcomparan cada función con una referencia de git. -
Snapshots base
Registra el estado actual de una base de código existente y falla solo con funciones nuevas o que empeoran.
-
Sugerencias de refactorización y
--fix
Reglas como cláusulas de guarda y extraer función auxiliar, y correcciones automáticas donde son seguras.
-
Formatos de salida
JSON, CSV, SARIF para GitHub code scanning y GitLab Code Quality.
-
Servidor de lenguaje
Inlay hints, hover y advertencias en VS Code, Neovim y Zed.
-
GitHub Action y hook de pre-commit
Ejecuta el mismo control en CI y antes de cada commit.
Preguntas Frecuentes¶
¿Cómo se calcula la complejidad? Aprende sobre el algoritmo de puntuación, qué aporta cada estructura de control y cómo afecta el anidamiento a la puntuación final.
¿Cómo se compara esto con PLR0912 de Ruff? Comprende las diferencias clave entre la complejidad ciclomática (Ruff) y la complejidad cognitiva (complexipy), y por qué podrías querer usar ambas.
¿Es esto un producto de SonarSource/Sonar? No. complexipy es un proyecto independiente inspirado en la investigación de G. Ann Campbell, pero no está afiliado ni respaldado por SonarSource.
Integraciones¶
Todos los editores usan complexipy lsp, un servidor de lenguaje con inlay hints, hover y advertencias que se actualizan mientras escribes. Instala complexipy primero (uv tool install complexipy).
Para VS Code, instala la extensión desde el Visual Studio Marketplace o desde OpenVSX. Para Neovim y Zed, consulta Integración con Editores.
Aprende Más¶
- Guía de Uso - instalación, el flujo básico de la CLI y solución de problemas
- Adoptar en una Base de Código Existente - línea base, bloquear código nuevo y luego bajar el umbral
- Configuración - archivos de configuración y la caché
- Diff y Snapshots - diff de complejidad y snapshots base
- Ignorados y Selección de Reglas - ignorados en línea y selección de reglas
- Opciones de CLI - todas las flags de CLI
- Integración con Editores - el servidor de lenguaje, los inlay hints y la configuración de VS Code, Neovim y Zed
- Referencia de la API - la API completa de Python
- Qué Significan las Puntuaciones - cómo funciona el algoritmo de puntuación
- Comparación con Ruff - complejidad cognitiva vs ciclomática
- Reglas de Refactorización - las reglas detrás de
--suggest-refactors - Registro de Cambios - qué cambió en cada versión
Inspirado en la investigación de Complejidad Cognitiva de G. Ann Campbell
complexipy es un proyecto independiente y no está afiliado ni respaldado por SonarSource
Desarrollado con ❤️ por @rohaquinlop y colaboradores