Gawain: новий інструмент для суворого контролю типів у Python

· Майбутнє

Gawain: новий інструмент для суворого контролю типів у Python

Gawain — це новий інструмент, який вимагає наявності анотацій типів для кожної змінної, параметра та атрибута в Python, примушуючи розробників відмовитися від неявних типів.

Gawain вимагає наявності анотацій типів для змінних, параметрів, значень, що повертаються, та атрибутів класів у коді Python, після чого запускає перевіряльник типів — ty або pyrefly — для підтвердження їхньої коректності.

Такі перевіряльники типів, як mypy, Pyright, ty та pyrefly, виводять тип змінної, якщо вона не має анотації. Правила ANN у ruff та flake8-annotations вимагають анотацій лише для функцій. gawain же наполягає на їх використанні також для змінних та атрибутів класів.

Я створив gawain лише тому, що ненавиджу dict[str, Any] і хотів щось із цим зробити. Якщо ваша відповідь на це: «але ж Python вже виводить типи сам» або «але ж моє IDE робить це за мене», тоді не використовуйте його, юний падаване.


Розглянемо 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 виводить:

[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 проходить перевірку, оскільки літерал має очевидний тип. PORT є константою, тому він вимагає Final[int].

Коли всі анотації на місці, gawain запускає перевіряльник типів для тих самих файлів і виводить отримані результати.

З ty (типовий перевіряльник) для 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).

Встановіть gawain із додатковим пакетом потрібного вам перевіряльника. ty є типовим, і додатковий пакет ty фіксує версію 0.0.100:

uv tool install "gawain[ty]"
# або
pip install "gawain[ty]"

Щоб використовувати pyrefly, встановіть додатковий пакет pyrefly, який фіксує версію pyrefly 1.4.1 і не встановлює ty:

uv tool install "gawain[pyrefly]"
# або
pip install "gawain[pyrefly]"

Потім оберіть його за допомогою checker = "pyrefly" у файлі [tool.gawain] або за допомогою прапорця --checker pyrefly.

docs/configuration.md пояснює цей перемикач.

Команда pip install gawain без додаткових пакетів встановлює лише утиліту gawain. У такому разі в системному PATH має бути присутній перевіряльник.

Попередження Використовуйте gawain обережно. ty перебуває на стадії бета-тестування, і його діагностика може змінюватися між версіями. Якщо це створює проблеми для вашого проєкту, використовуйте pyrefly або --no-types, щоб виконувати лише перевірку анотацій.

gawain check src/                  # анотації, потім типи
gawain check src/ --no-types       # лише анотації
gawain check src/ --checker pyrefly  # pyrefly замість ty
gawain check src/ --mode strict    # анотація для кожного присвоєння
gawain check src/ --format json    # один об'єкт JSON для інструментів

gawain повертає код 0, якщо нічого не знайдено, 1 — якщо виявлено помилку, і 2 — у разі помилки використання або якщо перевіряльник типів не може запуститися. Попередження перевіряльника типів виводяться, але не призводять до провалу перевірки.

GW000 позначає файл, який gawain не може прочитати, а GW900 і GW901 вказують на пошкоджене або невикористане пригнічення помилок. Щоб ігнорувати рядок, вкажіть код помилки:

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

docs/rules.md містить повний перелік правил, виключень та синтаксис пригнічення.

Типовий режим — obvious (очевидний). Назва може бути без анотації, якщо її значення має очевидний тип і назва більше ніколи не змінюється: літерал (count = 0), контейнер з літералів (ids = [1, 2, 3]) або виклик конструктора (user = User("ada")). Режим strict вимагає анотацію для кожного присвоєння:

[tool.gawain]
mode = "strict"

docs/rules.md містить точні правила для кожного режиму.

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

pre-commit встановлює хук із репозиторію, тому для збірки потрібен Rust 1.97 або новішої версії. docs/configuration.md детально описує [tool.gawain], шляхи та роботу хука.

Дані щодо продуктивності на стандартній бібліотеці CPython 3.14 (1 847 файлів, 974 586 рядків), медіана 30 запусків (5 для flake8-annotations):

gawain запущено з --no-types. Це один із тестів на одній машині (AMD Ryzen 7 3700X, WSL2).

  • docs/rules.md: правила, режими, виключення та пригнічення.
  • docs/configuration.md: шляхи, вивід, коди завершення, [tool.gawain] та pre-commit.
  • docs/benchmarks.md: як проводилися заміри вищевказаних показників.

gawain зчитує Python за допомогою ruff_python_parser і перевіряє типи за допомогою ty (обидва від Astral) або за допомогою pyrefly від Meta.

Я не знаю, мені просто подобаються артуріанські легенди. Ґавейн — це лицар Круглого столу, а талісманом є сокира Зеленого лицаря із зеленим поясом із поеми «Сер Ґавейн і Зелений лицар».

MIT. Див. файл LICENSE.

Оригінал: github.com

Про Що? — новини науки, технологій і світу