Realizar auditorías de código Python automáticamente

Seguir los estándares de PEP8, o cualquier otro, es algo que garantiza producir un código de mayor calidad. Pero es algo complicado. Tanto por desconcierto de todos los detalles de la norma como por descuido, no se siguen las recomendaciones. Para garantizar que el código siga fielmente los estándares se puede usar algún linter, como puede ser Pylint, que nos indique todos los incumplimientos de las recomendaciones para que se puedan subsanar. Veamos el uso básico de Pylint para realizar auditorías de código Python de una forma automática.

Instalación de Pylint

Pylint es un paquete de Python que se puede instalar desde PyPI mediante el uso del comando pep. Para ello solamente deberemos abrir una terminal y escribir el siguiente comando

pip install pylint

Una vez hecho esto deberemos poder acceder al comando pylint con el que se puede hacer una auditoría de código automática. La cual dará una puntuación hasta 10 para cada uno de los archivos de un proyecto, pudiendo ser incluso la puntuación negativa.

Archivo de ejemplo

Veamos el siguiente archivo.

class contador:
    def __init__(self, c=0):
        self.counter = c

    def add(self, v=1):
        self.counter += v


def suma(a, b=0):
    return a + b


if __name__ == "__main__":
    c = contador()
    c.add(5)

    valorResultado = suma(1, 2)

Es un código Python sencillo que implementa una clase Contador y una función suma(). Realmente no hace nada útil, pero sirve de ejemplo para ver el funcionamiento de Pylint. Para realizar una autoría de este archivo, al que he puesto el nombre de test.py, y ver en qué grado sigue el estándar PEP8 se puede hacer escribiendo la siguiente orden en la terminal.

% pylint test.py
************* Module test
test.py:1:0: C0114: Missing module docstring (missing-module-docstring)
test.py:1:0: C0103: Class name "contador" doesn't conform to PascalCase naming style (invalid-name)
test.py:1:0: C0115: Missing class docstring (missing-class-docstring)
test.py:2:23: W0621: Redefining name 'c' from outer scope (line 14) (redefined-outer-name)
test.py:5:4: C0103: Argument name "v" doesn't conform to snake_case naming style (invalid-name)
test.py:5:4: C0116: Missing function or method docstring (missing-function-docstring)
test.py:1:0: R0903: Too few public methods (1/2) (too-few-public-methods)
test.py:9:0: C0103: Argument name "a" doesn't conform to snake_case naming style (invalid-name)
test.py:9:0: C0103: Argument name "b" doesn't conform to snake_case naming style (invalid-name)
test.py:9:0: C0116: Missing function or method docstring (missing-function-docstring)
test.py:17:4: C0103: Constant name "valorResultado" doesn't conform to UPPER_CASE naming style (invalid-name)

------------------------------------------------------------------
Your code has been rated at 0.00/10 (previous run: 0.00/10, +0.00)

Lo que nos indica que tenemos una puntuación de 0 sobre 10 (un resultado realmente malo) y se incumplen 11 recomendaciones.

Solución de los problemas

Veamos a continuación los problemas que ha detectado
Pylint y cómo se pueden solucionar.

Missing module docstring

Este es un problema sencillo, pero bastante habitual. El archivo no tiene una documentación con una descripción de las funciones y clases que se pueden encontrar dentro de él. Para solucionar este problema solamente hay que agregar la documentación.

Class name doesn’t conform to PascalCase naming style

Otro problema habitual, para diferenciar las clases de las funciones los nombres de las primeras deben comenzar por mayúsculas y, en caso de estar formadas por más de una palabra, cada una de las palabras deben escribirse en mayúsculas. Esto es lo que se llama notación PascalCase (también conocido como UpperCamelCase). La solución de este problema es tan sencilla como renombrar la clase a Contador.

Missing class docstring

Al igual que en el módulo, no existe documentación para esta clase. Por lo que es aconsejable incluir una explicación de lo que hace la clase incluyendo un docstring después del constructor.

Redefining name from outer scope

El nombre c para un parámetro es demasiado corto y explica bien lo que hace, lo aconsejable es que este tenga por lo menos tres letras. Ya que es el valor con el que se inicia el contador una forma de solucionar esto es renombrar este parámetro a algo como init.

Argument name doesn’t conform to snake_case naming style

Al igual que los parámetros de la clase, los nombre de las argumente de las funciones deberían ser explicativos. Por eso nombres como v, a o b no son válidos. Lo mejor es darles nombres más significativos tales como value, number1 o number2 respectivamente.

Missing function or method docstring

Este es el mismo problema que se ha visto en el módulo y la clase, no existe documentación ni en los métodos de la clase ni en las funciones. Problema que se soluciona incluyendo la documentación.

Notes que no indica este error en el constructor de la clase __init__(). Esto es así porque la documentación que explique los parámetros de este elemento es el de la clase y, por lo tanto, no es necesario.

Too few public methods

La clase es muy sencilla solo tiene un método. Aunque para lo que se quiere es funcional, cuando esto sucede a lo mejor es mejor definir una función antes que una clase. Por eso aparece el error. La solución para este problema es agregar un segundo método a la clase, en este caso algo necesario puede ser una función de reinicio.

Constant name doesn’t conform to UPPER_CASE naming style

El nombre de la variable valorResultado incumple dos recomendaciones para una variable. El primero es que usa una notación tipo lowerCamelCase cuando las funciones y variables deberían en Python ser snake_case. Además, cómo el valor de la variable no se modifica durante la ejecución del programa esta es una constante, para las que se recomienda la notación UPPER_CASE.

En este caso se podría entender que la notación correcta sería snake_case, pero como el valor no se modifica en ningún lugar es mejor usar UPPER_CASE para indicar esto a otros programadores.

Archivo de ejemplo con las mejoras

Ahora teniendo en cuenta las mejoras el código del archivo quedará algo como los siguiente:

"""Archivo de ejemplo para ver el funcionamiento de Pylint"""


class Contador:
    """Clase Contador que suma ocurrencias"""
    def __init__(self, init=0):
        self.counter = init

    def add(self, value=1):
        """Agrega el valor indica, o por defecto 1, al contador"""
        self.counter += value

    def reset(self):
        """Resetea el contador"""
        self.counter = 0


def suma(number1, number2=0):
    """Suma dos números, si solo se indica 1 parámetro devuelve este"""
    return number1 + number2


if __name__ == "__main__":
    cont = Contador()
    cont.add(5)

    VALOR_RESULTADO = suma(1, 2)

Algo más legible y fácil de entender. Además, ahora la calidad del código ha subido de 0 a 10, lo que nos indica que se ha hecho un buen trabajo gracias a la realización de auditorías de código Python.

pylint test.py

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

Auditorías de código Python en un proyecto

En el ejemplo anterior se ha utilizado Pylint sobre un archivo en concreto, pero obviamente se pueden usar comodines para realizar la auditoría sobre una carpeta o proyecto. Por ejemplo, para revisar todo el código se podría usar algo como

pylint *.py

También se puede usar opciones para que solamente nos indique los archivos con peor puntuación. Algo que es útil si estamos revisando un proyecto grande y queremos centrarnos únicamente en los casos más graves. Para lo que se debe usar el parámetro --fail-under seguido de la puntuación de corte.

pylint --fail-under=8 **/*.py

Las opciones de configuración y sobre los errores detectados se puede ver en la documentación del proyecto.

Conclusiones

En la entrada de hoy se ha visto cómo se puede usar el paquete Pylint para realizar auditorías de código Python de forma automática. Auditorías con la que se puede encontrar fácilmente los incumplimientos del estándar PEP8 y solucionarlos de una manera rápida.

Al igual que las herramientas para formatear el código, los linter como Pylint deben ser algo que deberíamos incluir en nuestro flujo de trabajo, sea este u otro. Al incluir la documentación, nombres de variable, clases y funciones adecuadas se consigue un código más fácil de leer y entender, por lo que la productividad de los equipos aumenta. Algo que, en base a la teoría de los cristales rotos, provocará que el equipo sea más cuidadoso con el producto que crea. Produciendo un código de mayor calidad.

Imagen de Vitor Dutra Kaosnoff en Pixabay