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