Reducir la complejidad de Python
Archivos: $ARGUMENTS
La complejidad del código debe mantenerse baja preferiblemente. La complejidad se mide como el número de tokens léxicos de Python que forman parte del código imperativo: sintaxis que ejecuta algo. Las declaraciones organizan el código sin agregar lógica, por lo que son gratuitas.
Qué cuenta
imperative_tokens.py, junto a este archivo, es la definición.
No se cuenta:
- Cabeceras de
defyclass, desde el primer decorador hasta los dos puntos que abren el cuerpo: decoradores, parámetros, valores por defecto, clases base, anotación de retorno. Todo se evalúa una vez, con la definición, y declara una interfaz. - Anotaciones de tipo (
x: int = 1cuenta comox = 1, un simplex: intcomo nada) y alias de tipo (type). - Importaciones, comentarios, docstrings, nuevas líneas y sangría.
- El nombre de un argumento de palabra clave en una llamada:
f(clave=valor)pesa tanto comof(valor). Pasar un argumento por palabra clave es preferible en la mayoría de situaciones, por lo que no cuesta nada. - Calificación de atributos:
a.b.c.dpesa tanto comod. Una ruta con puntos nombra un solo objeto. Contarlo recompensaríafrom numpy import logsobrenp.log, o un alias local paraself.x, y ninguno cambia la lógica.
Se cuenta: cualquier otro token. Sentencias (if, for, while, try, with, return, raise, …), asignaciones, operadores, llamadas, literales, comprensiones y lambdas, con sus comas, dos puntos y ambos corchetes de un par. Por lo tanto, una llamada pesa uno más que el operador que hace lo mismo: a.update(b) son 4 tokens, a |= b son 3.
De un notebook (.ipynb), se cuentan las celdas de código. Una línea mágica o de shell (%config …, !pip …) cuenta como la llamada en la que IPython la convierte. Una celda bajo una magia de celda (%%bash, %%html) cuenta 0. La excepción es una magia de celda que ejecuta el cuerpo como Python (los ExecutionMagics de IPython, como %%time y %%capture): la magia cuenta como una línea mágica y el cuerpo como código. Una magia que no está integrada en el IPython instalado, como la de una extensión, cuenta 0 y el script imprime una advertencia: transmite esa advertencia en el informe. Un notebook cuyo kernel no es Python cuenta 0. El script importa IPython solo cuando se le da un notebook de Python, y le pregunta qué magias están integradas.
El conteo es un indicador
Un conteo más bajo es la evidencia de una simplificación, no la simplificación en sí.
- Se permiten refactorizaciones significativas: una nueva función auxiliar, una nueva clase base, un nuevo archivo. El conteo se compara entonces sobre todos los archivos afectados combinados (paso 4), por lo que la lógica movida entre archivos se neutraliza a cero.
- Necesita su propia justificación: mover lógica a donde el script no mira, que es un valor por defecto, un argumento de decorador, una expresión de clase base o una nueva dependencia. La propuesta indica por qué el cambio es bueno aparte del conteo más bajo.
- Prohibido: código en una cadena para
evaloexeco ejecución externa similar. - Enlinerar una variable que se usa una sola vez es aceptable solo cuando no perjudica la legibilidad. Un buen nombre para una variable intermedia ayuda al lector a entender la intención.
- No son reducciones: eliminar comportamiento (validación en un límite, manejo de errores, un caso soportado), y cambiar legibilidad por unos pocos tokens (una línea densa, una coma final eliminada).
Las reglas propias del proyecto (CLAUDE.md, guías de codificación) están por encima del conteo.
Cambios que no son estrictamente equivalentes
Un cambio puede alterar el comportamiento en aras de la simplicidad cuando un argumento demuestra que el programa se mantiene correcto. La propuesta indica qué difiere, en qué entradas, y el argumento con su evidencia en el código:
- La entrada diferente no puede ocurrir. Evidencia: el código que construye o valida el valor.
- Nadie observa la diferencia. Evidencia: cada consumidor del valor, listado.
- La diferencia es observable pero inofensiva: otros extraen de un generador con semilla, un algoritmo más lento, un error lanzado antes. Esto necesita el acuerdo explícito del usuario. También cualquier diferencia que un valor de retorno público, una salida escrita o una prueba pueda ver.
Algunos ejemplos, para mostrar la forma del argumento. Cualquier otro cambio que altere el comportamiento se argumenta de la misma manera, se parezca o no a uno de estos:
| Forma más simple | Reemplaza | Qué difiere |
|---|---|---|
x or default | x if x is not None else default | un x falso (0, "", []) también se reemplaza |
zip(a, b) | indexar ambos con range(len(a)) | un b más corto trunca silenciosamente; strict=True mantiene la comprobación |
a // b | int(a / b) | operandos negativos redondean al otro lado |
max(xs, key=f) | sorted(xs, key=f)[-1] | en un empate, gana el primero de los elementos iguales, no el último |
xs.sort() | xs = sorted(xs) | la lista que el llamador pasó es mutada |
Counter(xs) | un bucle de conteo | una clave faltante devuelve 0 en lugar de lanzar una excepción |
un @dataclass, leído como row.name | un registro de diccionario, leído como row["name"] | la indexación, .get, desempaquetado ** y serialización JSON del registro dejan de funcionar |
El argumento se basa en el código, no en los datos de hoy: "el archivo no tiene duplicados" no es uno, y tampoco "probablemente único". Eliminar comportamiento sigue excluido: la validación en un límite no se argumenta.
Cuando no esté seguro, el usuario decide. Si la evidencia es incompleta (un consumidor fuera del repositorio, un valor construido por código que no se puede leer) o no está claro que una diferencia sea inofensiva, no lo resuelva de ninguna manera. Ofrezca el cambio con lo que difiere y lo que se desconoce, continúe con las otras propuestas, y aplíquelo solo con el acuerdo del usuario.
Formas de la biblioteca estándar
Una muestra de casos frecuentes, para mostrar cómo se ve un reemplazo de este tipo. No es un catálogo: los builtins, la biblioteca estándar y las dependencias instaladas del proyecto ofrecen muchos más, y un reemplazo que no está en la tabla es tan válido como uno que sí está.
| Forma estándar | Reemplaza | Qué difiere |
|---|---|---|
@dataclass, con field(default_factory=list), order=True, frozen=True | un __init__ que solo almacena sus parámetros; un __eq__, __repr__, __lt__, __hash__ escrito a mano | una clase que no tenía __eq__ ahora compara por valor y no se puede hashear (eq=False mantiene la identidad); __eq__ también compara la clase; un None explícito ya no se convierte en el valor por defecto |
any(p(x) for x in xs), all(…), next(filter(p, xs), None) | un bucle de bandera o búsqueda con break | nada |
defaultdict(list) | if key not in groups: groups[key] = [] | leer una clave faltante la inserta |
@cache, @cached_property | un diccionario memo; un atributo perezoso if self._x is None | @cache en un método mantiene viva cada instancia en la que se llamó; la propiedad se reinicia con del, no asignando None |
itemgetter("foo"), str.strip, operator.mul | un lambda que solo indexa, llama a un método o aplica un operador | str.strip lanza una excepción en un valor que no es str |
Path(path).read_text() | with open(path) as file: y file.read() | nada |
name.removeprefix(prefix), line.partition("=") | startswith y un slice; split y una comprobación de longitud | nada |
chain.from_iterable(xss) | [x for xs in xss for x in xs] | un iterador: envuélvalo en list donde el resultado se indexe o se lea dos veces |
batched(xs, n) | xs[i:i + n] sobre range(0, len(xs), n) | un iterador de tuplas, no una lista de slices |
@singledispatch | una cadena de isinstance | gana la clase registrada más específica, no la primera prueba que coincide; el argumento despachado es el primero, pasado por posición |
@singledispatch y los argumentos de @dataclass mueven lógica a una cabecera, donde el script no mira. Su razón aparte del conteo: los métodos generados siguen la lista de campos y no pueden desviarse de ella, y cada tipo recibe una función propia, a la que un nuevo tipo no toca.
Otras formas ayudan solo dependiendo del contexto, por lo que necesitan consideración adicional:
itertools.productoitertools.combinationspueden reemplazar un bucle anidado.functools.reducepuede reemplazar un pliegue que no tiene builtin.
Pasos
-
Línea base. Ejecute el script en los archivos del argumento con el intérprete del proyecto (Python 3.12 o posterior) y conserve la salida:
python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <archivo.py | notebook.ipynb> [...]Ejecute las pruebas ahora: una suite que falla antes del cambio no puede verificar nada después. Si el usuario solo pidió una medición, repórtela y deténgase.
-
Proponga. Lea el código para entender qué calcula, no para buscar patrones, y pregunte de cada función, bucle y rama si el mismo resultado se puede expresar con menos. Las listas y tablas en esta skill muestran cómo se ve una simplificación. No son el espacio de búsqueda: la mayor parte de lo que se puede eliminar es específico del código en cuestión, y ninguna lista lo anticipa. Una pasada que solo verifica los patrones listados es incompleta.
Los hallazgos habituales, aproximadamente en orden de rendimiento:
- código muerto: funciones, parámetros y ramas no utilizados que no se pueden tomar;
- la misma lógica escrita dos veces, aquí o en otro archivo, que un ayudante compartido o una clase base contendría una vez;
- código escrito a mano que la biblioteca estándar, un builtin o una dependencia instalada ya proporciona; utilidades de la biblioteca estándar como
itertools,functools,operator,collectionsodataclassespueden ayudar, y "Formas de la biblioteca estándar" arriba lista los casos frecuentes; - bucles que construyen un valor: una comprensión suele ser mejor que un bucle, y ocasionalmente el builtin
filteromapes más simple que una comprensión; - llamadas a métodos que un operador sobrecargado reemplaza:
a | bpora.union(b),a |= bpora.update(b),a @ bpora.dot(b). Verifique primero los tipos de los operandos:|=en un conjunto necesita un conjunto, mientras que.update()acepta cualquier iterable; - ramas que colapsan en datos (un mapeo) o en la ruta general;
- estado y conversiones que existen solo para ser deshechos;
- comprobaciones defensivas fuera de un límite del programa;
- código más estricto de lo que necesitan sus entradas, donde una forma más simple difiere solo en entradas que no pueden ocurrir o en formas que nadie observa (tabla anterior).
Luego revise el código una vez más, las funciones más largas primero, para lo que no encaja en ninguno de estos: un algoritmo o estructura de datos diferente que hace que la contabilidad sea innecesaria, un cálculo reordenado para que un caso especial desaparezca, una función de una dependencia que el proyecto ya usa que hace todo el trabajo, dos funciones que difieren en un valor. Dicha propuesta se rige por las mismas reglas que cualquier otra listada.
Para pesar un fragmento, como las líneas de una propuesta antes y después, canalícelo al script sin un argumento de archivo. Imprime solo el conteo. El fragmento debe poder analizarse por sí solo, así que quite la sangría:
python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <<'EOF' no_contado |= set(range(primero, ultimo)) EOFMuestre cada propuesta como forma de código, las líneas clave antes y después, con el ahorro esperado en tokens, los otros archivos que toca y cualquier justificación o argumento que soliciten las secciones anteriores. Aplique con la aprobación del usuario, o directamente si ya pidió que se hicieran los cambios.
-
Aplique y verifique, una propuesta a la vez, para que un fallo señale su causa.
- Antes de la primera edición a un archivo fuera de la línea base, mídalo y agréguelo a la línea base. Un archivo nuevo comienza en 0.
- Las pruebas pasan, sin cambios. Una prueba editada junto con el código que verifica ya no lo verifica; si una debe cambiar (llama a un ayudante eliminado), dígalo.
- Las pruebas que nunca ejecutan las líneas cambiadas no prueban nada. Para esas líneas, ejecute la versión antigua (
git stash, ogit show HEAD:<ruta>en un archivo temporal) y la nueva en las mismas entradas, incluidos los casos límite, y compare las salidas. Los resultados de punto flotante son idénticos, o el informe indica el tamaño de la diferencia. - Un cambio que no es estrictamente equivalente se compara en las entradas que admite su argumento. Luego verifique el argumento en sí: lea el código que construye el valor, o busque cada consumidor. La evidencia que no se sostiene descarta la propuesta.
- Un cambio en el comportamiento público (una firma, un tipo de excepción, el orden de una salida) no es un cambio equivalente. Necesita el acuerdo explícito del usuario.
-
Vuelva a medir. Ejecute el script en todos los archivos afectados: los del argumento y cualquier otro archivo que el cambio editó o creó. Un archivo eliminado termina en 0. El total combinado es menor que la línea base combinada, o el cambio se revierte. También se revierte uno que falló en el paso 3.
-
Informe. Por archivo afectado y combinado: tokens antes, después y la diferencia. Luego qué verificó la equivalencia (qué pruebas, qué comparaciones directas), cada cambio que no es estrictamente equivalente, con qué difiere y su argumento, cada cambio que espera la decisión del usuario, y cada propuesta que se descartó, con el motivo.