Gawain: una nueva herramienta para el control estricto de tipos en Python

· Futuro

Gawain: una nueva herramienta para el control estricto de tipos en Python

Gawain es una herramienta que exige anotaciones de tipo para cada variable, parámetro y atributo en Python, obligando a los desarrolladores a prescindir de los tipos implícitos.

gawain requiere anotaciones de tipo en las variables, parámetros, retornos y atributos de clase del código Python, y luego ejecuta un comprobador de tipos, ty o pyrefly, para verificar que los tipos sean correctos.

Los comprobadores de tipos como mypy, Pyright, ty y pyrefly infieren el tipo de una variable que no tiene anotación. Las reglas ANN de ruff y flake8-annotations solicitan anotaciones solo en las funciones. gawain también las solicita en las variables y los atributos de clase.

Creé gawain solo porque odio dict[str, Any] y quería hacer algo al respecto. Si su respuesta a esto es «pero Python ya infiere eso» o «pero mi IDE lo infiere por mí», entonces no lo use, pequeño padawan.

Dado shop.py:

PORT = 8080

retries = 3

total = compute()

def send(to, body):
    print(f"to {to}: {body}")

class Order:
    def __init__(self, items: list[str]) -> None:
        self.items = items

gawain check shop.py imprime:

[presence]
shop.py:1:1    GW001 variable 'PORT' has no type annotation
shop.py:3:1    GW001 variable 'total' has no type annotation
shop.py:6:5    GW003 function 'send' has no return type annotation
shop.py:6:10   GW002 parameter 'to' of function 'send' has no type annotation
shop.py:6:14   GW002 parameter 'body' of function 'send' has no type annotation
shop.py:12:14  GW004 attribute 'items' is not declared in the body of class 'Order'

6 errors (presence). Type check skipped until presence errors are fixed.

retries = 3 pasa, porque un literal tiene un tipo obvio. PORT es una constante, por lo que necesita Final[int].

Cuando todas las anotaciones están en su lugar, gawain ejecuta el comprobador de tipos en los mismos archivos e imprime lo que este reporta.

Con ty, el valor predeterminado, para prices.py:

def total(prices: list[int]) -> int:
    return "0"
[types]
prices.py:2:12  ty[invalid-return-type] Return type does not match returned value: expected `int`, found `Literal["0"]`

1 error (types).

Instale gawain con el extra del comprobador de tipos que desee. ty es el comprobador predeterminado, y el extra ty lo fija en la versión 0.0.100:

uv tool install "gawain[ty]"
# o
pip install "gawain[ty]"

Para usar pyrefly en su lugar, instale el extra pyrefly, que fija pyrefly en la versión 1.4.1 y no instala ty:

uv tool install "gawain[pyrefly]"
# o
pip install "gawain[pyrefly]"

Luego, elíjalo con checker = "pyrefly" en [tool.gawain], o con --checker pyrefly.

docs/configuration.md explica el cambio.

pip install gawain sin un extra solo instala el comando gawain. Entonces necesita un comprobador en el PATH, o

Advertencia Use gawain con cuidado. ty está en fase beta y sus diagnósticos pueden cambiar entre versiones. Si eso es un problema para su proyecto, use pyrefly o --no-types para ejecutar solo las comprobaciones de anotación.

gawain check src/                  # anotaciones, luego tipos
gawain check src/ --no-types       # solo anotaciones
gawain check src/ --checker pyrefly  # pyrefly en lugar de ty
gawain check src/ --mode strict    # una anotación en cada asignación
gawain check src/ --format json    # un objeto JSON, para herramientas

gawain finaliza con 0 cuando no se reporta nada, con 1 cuando reporta un error, y con 2 en caso de error de uso o cuando el comprobador de tipos no puede ejecutarse. Las advertencias del comprobador de tipos se imprimen, pero no hacen que la comprobación falle.

GW000 marca un archivo que gawain no puede leer, y GW900 y GW901 marcan una supresión rota o sin usar. Para silenciar una línea, nombre el código:

value = load()  # gawain: ignore[GW001]

docs/rules.md contiene las reglas completas, las exenciones y la sintaxis de supresión.

El modo predeterminado es «obvio». Un nombre puede ir sin anotación cuando su valor tiene un tipo obvio y el nombre nunca se vuelve a asignar: un literal (count = 0), un contenedor de literales (ids = [1, 2, 3]) o una llamada al constructor (user = User("ada")). strict solicita una anotación en cada asignación:

[tool.gawain]
mode = "strict"

docs/rules.md tiene las reglas exactas de cada modo.

repos:
- repo: https://github.com/matheuzgomes/gawain
  rev: v0.3.0
  hooks:
  - id: gawain

pre-commit instala el hook desde el código fuente de este repositorio, por lo que compilarlo requiere Rust 1.97 o superior.

docs/configuration.md cubre [tool.gawain], las rutas y el hook en detalle.

En la biblioteca estándar de CPython 3.14 (1.847 archivos, 974.586 líneas), mediana de 30 ejecuciones (5 para flake8-annotations):

gawain se ejecutó con --no-types. Este es un punto de referencia en una máquina (AMD Ryzen 7 3700X, WSL2).

docs/benchmarks.md tiene las versiones y los comandos para ejecutarlo de nuevo.

  • docs/rules.md: reglas, modos, exenciones y supresión.
  • docs/configuration.md: rutas, salida, códigos de salida, [tool.gawain] y pre-commit.
  • docs/benchmarks.md: cómo se midieron las cifras anteriores.

gawain lee Python con ruff_python_parser y comprueba tipos con ty, ambos de Astral, o con pyrefly, de Meta.

No lo sé, solo me gustan los cuentos artúricos. Gawain es un caballero de la Mesa Redonda, y la mascota es el hacha del Caballero Verde con el cinturón verde de Sir Gawain y el Caballero Verde.

MIT. Consulte LICENSE.

Original: github.com

Adaptación al español con ayuda de inteligencia artificial. Читати українською

¿De qué va? — la edición en español de «Про Що?»