Простые DSL, которые работают

Год назад я выпустил auto-typing-final — исправитель и линтер, реализующий правило из руководства по стилю сообщества Python Raiffeisenbank России: «используйте typing.Final для констант». Сейчас он интегрирован во всей нашей кодовой базе (даже есть расширение для VS Code).

Вдохновлённый работой над Ty в Ruff и PR Карла Мейера с фреймворком тестирования на основе Markdown в Ruff, где показано, как встроенные примеры тестов в Markdown могут упростить и тестирование, и документацию.

Чтобы упростить и тесты, и документацию, я реализовал простой внутренний DSL на основе Markdown для определения сценариев преобразований прямо в тексте:

### Множественные присваивания с `Final`

```python
a: Final = 1  # удалить («удалить» означает, что нужно убрать «Final». Есть ещё «вставить» — обратное действие)
a = 2

Такие примеры заменили сложную параметризацию с многострочными строками.

Почему этот внутренний DSL работает:

• Повышает ясность. Заголовки описывают каждый тестовый случай, а блоки кода с разделителями отделяют входные данные, ожидаемые изменения и аннотации.

• Единый источник истины. Один и тот же фрагмент Markdown одновременно управляет параметризацией pytest и служит пользовательской документацией.

Вывод#

Небольшие DSL, подобные этому, работают эффективно: их легко парсить, читать и писать. Этот пример доказывает, что порой самые простые инструменты оказывают наибольшее влияние.