Referencia de la API¶
La API completa de Python que expone complexipy. Importa todo desde el paquete
complexipy. Para ejemplos de uso, consulta la sección
API de Python más abajo.
# Funciones principales
file_complexity(path: str, check_script: bool = False, no_ignore: bool = False, with_plans: bool = True) -> FileComplexity
code_complexity(source: str, check_script: bool = False, no_ignore: bool = False, with_plans: bool = True) -> CodeComplexity
collect_all_ignored_locations(paths: List[str], exclude: List[str], invocation_path: str = ".") -> Tuple[List[IgnoredLocation], List[str]]
collect_removable_ignored_locations(paths: List[str], exclude: List[str], max_complexity_allowed: int, invocation_path: str = ".") -> Tuple[List[RemovableIgnore], List[str]]
compute_diff(current_files: List[FileComplexity], git_ref: str, invocation_path: Optional[str] = None) -> List[DiffEntry]
has_regressions(entries: List[DiffEntry], max_complexity: int) -> bool
# Tipos de retorno
FileComplexity:
├─ path: str (relative to the working directory, or absolute when outside it)
├─ file_name: str
├─ complexity: int
└─ functions: List[FunctionComplexity]
FunctionComplexity:
├─ name: str
├─ complexity: int
├─ line_start: int
├─ line_end: int
├─ line_complexities: List[LineComplexity]
└─ refactor_plans: List[RefactorPlan]
RefactorPlan:
├─ kind: str
├─ title: str
├─ line_start: int
├─ line_end: int
├─ column_start: int
├─ current_complexity: int
├─ estimated_reduction: int
├─ estimated_complexity_after: int
├─ rule_id: str
├─ category: RuleCategory
├─ applicability: Applicability
├─ description: str
├─ explanation: str
├─ references: List[str]
├─ suggestion: Optional[CodeSuggestion]
├─ help: Optional[str]
└─ doc_url: str
CodeSuggestion:
├─ replacement: str
├─ applicability: Applicability
├─ description: str
└─ insertions: List[CodeInsertion]
CodeInsertion:
├─ before_line: int
└─ text: str
RuleCategory: Complexity | Readability
Applicability: MachineApplicable | MaybeIncorrect | Informational
LineComplexity:
├─ line: int
└─ complexity: int
IgnoredLocation:
├─ path: str
├─ line: int
└─ comment: str
CodeComplexity:
├─ complexity: int
└─ functions: List[FunctionComplexity]
DiffEntry:
├─ file_path: str
├─ func_name: str
├─ old_complexity: Optional[int]
├─ new_complexity: Optional[int]
└─ status: DiffStatus (property)
DiffStatus: REGRESSED | IMPROVED | UNCHANGED | NEW | REMOVED
Errores¶
file_complexity lanza ValueError cuando el archivo no se puede leer o decodificar como UTF-8, o no se puede analizar sintácticamente. code_complexity lanza ValueError cuando el código no se puede analizar sintácticamente. Un error interno en cualquier función de análisis también aparece como ValueError, así que un solo except ValueError omite un archivo que no se puede analizar.
API de Python¶
Analizar Archivos¶
from complexipy import file_complexity
# Analizar un archivo
result = file_complexity("src/main.py", check_script=True)
print(f"Total complexity: {result.complexity}")
print(f"File path: {result.path}")
# Iterar sobre las funciones
for func in result.functions:
print(f"{func.name}:")
print(f" Complexity: {func.complexity}")
print(f" Lines: {func.line_start}-{func.line_end}")
# Analizar sin respetar los comentarios de ignorado en línea
result = file_complexity("src/main.py", no_ignore=True)
Analizar Cadenas de Código¶
from complexipy import code_complexity
# Analizar fragmento de código
code = """
def calculate_discount(price, customer):
if customer.is_premium:
if price > 100:
return price * 0.8
else:
return price * 0.9
return price
"""
result = code_complexity(code, check_script=True)
print(f"Complexity: {result.complexity}")
for func in result.functions:
print(f"{func.name}: {func.complexity}")
# Analizar cadena de código sin respetar los comentarios de ignorado
result = code_complexity(code, no_ignore=True)
Ambas funciones construyen planes de refactorización por defecto. Pasa
with_plans=False cuando solo necesites las puntuaciones: refactor_plans
queda vacío y el análisis omite el trabajo de los planes.
Comparar Contra una Referencia de Git¶
compute_diff compara los resultados de complejidad actuales contra una
referencia de git (commit, etiqueta o rama) y devuelve objetos DiffEntry -
uno por función que cambió, apareció o desapareció. has_regressions informa
si alguna entrada supera un umbral de complejidad (una función REGRESSED o NEW
por encima de max_complexity). Las entradas no llevan los cuerpos de las
funciones, así que una función movida o renombrada cuenta como NEW; solo
--diff, que compara los cuerpos, deja pasar una copia exacta. Cada archivo se
lee del repositorio de git que lo contiene, en su propia ruta, y un submódulo
en el commit que fija su repositorio exterior, igual que con --diff, así que
un archivo movido desde la referencia reporta sus funciones como NEW: su ruta
anterior no está entre los archivos que pasas. Igual que --diff, necesita Git
2.30 o posterior en tu PATH. invocation_path, por defecto
el directorio de trabajo, ancla las rutas de archivo relativas y hace el papel
del directorio donde empieza una ejecución de la CLI.
from complexipy import (
compute_diff,
has_regressions,
file_complexity,
DiffEntry,
DiffStatus,
)
# Analizar el estado actual de los archivos de interés
current = [file_complexity(p) for p in changed_files]
# Comparar contra una referencia de git (el directorio de trabajo es el cwd por defecto)
entries = compute_diff(current, "origin/main")
# Filtrar regresiones por encima de tu umbral
regressions = [
e
for e in entries
if e.status == DiffStatus.REGRESSED and e.new_complexity > 15
]
# O usar el control de ratchet directamente (falla con REGRESSED/NEW sobre el umbral)
if has_regressions(entries, 15):
raise SystemExit("Regresiones de complejidad detectadas")
DiffEntry expone file_path, func_name, old_complexity y
new_complexity (cualquiera puede ser None para funciones NEW / REMOVED),
más la propiedad status. status es un miembro de
DiffStatus - un enum basado en str, por lo que compara igual a su valor
de cadena (p. ej. DiffStatus.REGRESSED == "REGRESSED").
for e in entries:
if e.status != DiffStatus.UNCHANGED:
print(f"{e.file_path}::{e.func_name}: {e.status} "
f"{e.old_complexity} -> {e.new_complexity}")
Uso Práctico de la API¶
Ejemplo: Hook de Pre-commit
#!/usr/bin/env python3
"""Verifica la complejidad de los archivos Python en staging."""
import sys
from pathlib import Path
from complexipy import file_complexity
MAX_COMPLEXITY = 15
def main():
# Obtener los archivos Python en staging (integrar con git)
staged_files = get_staged_python_files()
violations = []
for filepath in staged_files:
result = file_complexity(str(filepath))
for func in result.functions:
if func.complexity > MAX_COMPLEXITY:
violations.append({
'file': filepath,
'function': func.name,
'complexity': func.complexity,
'line': func.line_start
})
if violations:
print("Complexity violations found:")
for v in violations:
print(f" {v['file']}:{v['line']} - "
f"{v['function']} (complexity: {v['complexity']})")
sys.exit(1)
print("All functions pass complexity check!")
sys.exit(0)
if __name__ == "__main__":
main()
Ejemplo: Panel de Calidad de Código
from pathlib import Path
from complexipy import file_complexity
import json
def analyze_project(root_path: str):
"""Genera un reporte de complejidad para todo el proyecto."""
project = Path(root_path)
results = []
for py_file in project.rglob("*.py"):
if "venv" in str(py_file) or ".venv" in str(py_file):
continue
try:
result = file_complexity(str(py_file))
results.append({
'file': str(py_file),
'complexity': result.complexity,
'functions': [
{
'name': f.name,
'complexity': f.complexity,
'line_start': f.line_start,
'line_end': f.line_end
}
for f in result.functions
]
})
except Exception as e:
print(f"Error analyzing {py_file}: {e}")
# Ordenar por complejidad
results.sort(key=lambda x: x['complexity'], reverse=True)
# Guardar reporte
with open("complexity-report.json", "w") as f:
json.dump(results, f, indent=2)
# Imprimir resumen
total_files = len(results)
total_complexity = sum(r['complexity'] for r in results)
avg_complexity = total_complexity / total_files if total_files else 0
print(f"Analyzed {total_files} files")
print(f"Total complexity: {total_complexity}")
print(f"Average complexity: {avg_complexity:.2f}")
# Los 10 archivos más complejos
print("\nTop 10 most complex files:")
for r in results[:10]:
print(f" {r['file']}: {r['complexity']}")
if __name__ == "__main__":
analyze_project("./src")