Saltar a contenido

complexipy

complexipy

Análisis ultrarrápido de complejidad cognitiva para Python, escrito en Rust.

PyPI Downloads License

Instalación • Inicio Rápido • Funcionalidades • Integraciones • Aprende Más • Complexipy Teams

Gráfico de barras del tiempo de pared para puntuar la complejidad cognitiva del código de Django con complexipy, flake8-cognitive-complexity y pylint-cognitive-complexity Gráfico de barras del tiempo de pared para puntuar la complejidad cognitiva del código de Django con complexipy, flake8-cognitive-complexity y pylint-cognitive-complexity

Puntuando la complejidad cognitiva del código de Django (2.929 archivos). Puntos de referencia

Instalación

uv tool install complexipy
uv add complexipy
pip install complexipy

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:

def example1(a, b, c):
    if a:        # +1
        return 1
    if b:        # +1
        return 2
    if c:        # +1
        return 3
    return 4
def example2(a, b, c):
    if a:        # +1
        if b:    # +2 (1 + nesting_level)
            if c:  # +3 (1 + nesting_level)
                return 1
    return 4

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

complexipy puntúa cada función de checkout.py, marca apply_discount como fallida con 14 frente a un límite de 10 y sugiere extraer una función auxiliar

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.

    Cómo funcionan las puntuaciones

  • Bloquea solo lo que un cambio empeora


    --diff y --staged comparan cada función con una referencia de git.

    Diff de complejidad

  • Snapshots base


    Registra el estado actual de una base de código existente y falla solo con funciones nuevas o que empeoran.

    Snapshots

  • Sugerencias de refactorización y --fix


    Reglas como cláusulas de guarda y extraer función auxiliar, y correcciones automáticas donde son seguras.

    Reglas de refactorización

  • Formatos de salida


    JSON, CSV, SARIF para GitHub code scanning y GitLab Code Quality.

    Formatos de salida

  • Servidor de lenguaje


    Inlay hints, hover y advertencias en VS Code, Neovim y Zed.

    Integración con editores

  • GitHub Action y hook de pre-commit


    Ejecuta el mismo control en CI y antes de cada commit.

    Integración con CI/CD

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

- uses: rohaquinlop/complexipy-action@v9
  with:
      paths: .
      max_complexity_allowed: 10
      output_json: true
repos:
    - repo: https://github.com/rohaquinlop/complexipy-pre-commit
      rev: v9.0.0
      hooks:
          - id: complexipy

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


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