A year ago, I released auto-typing-final, a fixer and linter enforcing Raiffeisenbank Russia Python Community style-guide rule to “use typing.Final
for constants.” It’s now integrated throughout our codebase (there’s even a VS Code extension).
Inspired by Ty’s work on Ruff and Carl Meyer’s Markdown-based test framework PR in Ruff, which demonstrated how embedding example-driven tests in Markdown can simplify both testing and documentation.
To streamline both tests and documentation, I introduced a simple Markdown-based internal DSL for defining transformation scenarios inline:
### Multiple Assignments with `Final`
```python
a: Final = 1 # remove ("remove" means that "Final" should be stripped out. There's also "insert"—the opposite)
a = 2
Such examples replaced complex parametrization with multi-line strings.
Why This Internal DSL Works:
Enhanced Clarity. Headings describe each test case, and fenced code blocks separate input, expected changes, and annotations.
Single Source of Truth. The same Markdown snippet powers pytest parameterization and user-facing documentation.
So… Link to heading
Small DSLs like this work well: they’re easy to parse, easy to read and easy to write. This showcase proves that sometimes the simplest tools have great impact.