py-checks

Your project's architecture, checked like code.

English · Русский

A linter knows the language; it does not know your project. It will not tell you that an ORM model has wandered into a use case, that a Numeric column was left without a CHECK, that datetime.now() is called in the domain rather than behind a port. These are not language errors — they are broken conventions, and until now review caught them: by eye, differently for each reviewer, from scratch every time.

py-checks is an engine for conventions like these. The library brings the rules, the project brings its architecture: the names of the layers, the list of sealed zones, where the ORM lives, what bounds a column. Without the project's tables the rules stay silent — the library does not guess what your domain is called.

src/app/modules/cashout/application/offer.py:34:9: determinism: uuid4() is not deterministic;
    the identifier is handed out at the edge and passed inwards
src/app/infra/database/models/bet.py:51:5: model-columns: stake is a Numeric with no bound;
    money is described by Numeric(18, 4)
src/app/presentation/api/v1/routers/bets.py:22:1: edge-declarations: POST /bets
    did not name a response_model

Why

• A convention stops being spoken. The rule is written once, with its reason, and checked on every commit — rather than recalled at review by whoever remembers it.
• The rule is universal, the table is yours. One rule, "this call lives only here", covers both the transaction boundary and the ban on float in the domain. The library contains not one name from your project.
• A refusal explains itself. The message says what is wrong and what to write instead, not "violation of rule #14".
• An exemption costs one line and owes a reason. # check-ok: raw-sql: a liveness probe, there is no ORM form of it — a mark without a reason is itself a violation.
• We do not do other people's work. What ruff, pyright and import-linter can do stays theirs; what was handed over, and why, is written down in docs/service.md.

Install

uv add --dev python-checks

Installed as python-checks, called as py-checks: a neighbour holds the short name on PyPI, while the command, the settings section and the package stayed as they were.

Needs Python 3.14+. Dependencies: libcst, pydantic, pydantic-settings, rich, typer.

In a minute

Put a py-checks.toml next to pyproject.toml:

src = "src"

[module-length]
max-lines = 300

# Rules that depend on place only work in the zones you name.
[model-columns]
zones = ["infra/database/models"]
instead = { Float = "a Float column drifts; state is exact, use Numeric" }

[determinism]
zones = ["modules/*/domain", "modules/*/application"]
instead = { "datetime.now" = "take the clock as a port", "uuid4" = "hand the id out at the edge" }

and run:

py-checks run          # check `src`
py-checks run --fix    # and repair what repairs itself
py-checks list         # which rules exist and which are on
py-checks explain determinism   # what a rule asks for and what it can be told
py-checks doctor       # and whether the config itself holds together

The settings can also live in a [tool.py-checks] section of pyproject.toml — but one of the two: two places at once is an error to this library, not a merge.

What is checked

Twenty-eight rules in nine groups:

Every rule explains itself in full — py-checks explain <code> prints the docstring with the reason and the list of settings. A worked set of tables for a typical service is in docs/service.md.

Three kinds of rule

What a rule is handed to judge, the rule declares itself, in its scope:

• file — a parsed source file; most rules are these;
• project — the root: the manifest, the agreement of the repository's files with one another;
• environment — the same, but it needs a live database or a long run. An ordinary run leaves these out: py-checks run --all, or by name; their place is CI.

Marks

A line can be taken out of a rule's judgement, but you have to say why:

text("SELECT 1")  # db-ok: raw-sql: a liveness probe, there is no ORM form of it

The canonical form is # check-ok: <code>: <reason>, and it lifts exactly one rule. Every group has a short word of its own (# db-ok, # type-ok, # signature-ok, …): a person remembers the group, not twenty-eight codes.

A line may carry several marks — a signature written in a column gathers them on its last line:

    ) -> object:  # signature-ok: this is how pydantic calls it  # type-ok: raw input

A mark with no code, with a typo in the code, or with no reason is a violation itself. A silently dead mark looks like a disabled check, while the check is in fact running and simply does not see it.

pre-commit

- repo: https://github.com/Armontex/py-checks
  rev: v0.3.1
  hooks:
    - id: py-checks
      args: [--fix]          # repair what repairs itself
    - id: py-checks-sync     # contracts and `.env.example` rebuilt

One hook rather than one per rule: which rules run is the config's decision. A set of rules is called with args: [--select, "<code>,<code>"]; a repeated flag does the same.

It has to stand before ruff-format: the autofix writes characters, not columns, and the project's formatter lays the signature out.

Everything else — ruff, pyright, import-linter, commitizen — the project declares itself: each has a hook written by its own authors.

Import contracts

The project's layers are described once, and .importlinter is built from that:

[contracts.layers]
domain = ["domain"]
application = ["application", "domain"]
presentation = ["presentation", "application"]

py-checks sync           # build
py-checks sync --check   # fail if the file has fallen behind

It is built not only from the table but from what is on disk: a layer that does not exist is left out of the contract — otherwise import-linter would fail on the first module that is not there. The graph itself is walked by import-linter's own hook.

The header of the built file can be your own — header in [contracts], # included; as with .env.example, it is for a project whose comments are in another language.

The environment example

The name of a variable is known to the settings field — it declares it as validation_alias, and config-fields watches for that. So .env.example is derived from the same classes the variables are read into, and there is no reason to keep it by hand: it falls out of step silently, and that is noticed when the variable turns out to be missing in production.

[env-example]
settings = ["myservice.config.settings:Settings"]

The same py-checks sync builds it alongside the contracts. The root class is enough: it has already listed its sections as its own fields, and repeating that list in the settings would mean keeping a second one that drifts from the first. A section field does not become a variable — it has no name of its own in the environment. What goes into the file is the variable's name, its default, the first paragraph of the class docstring and the field's description if it has one — so the explanation lives next to the field rather than in a file that outlives it.

The header can be written by the project as well — header = "# Generated by py-checks.", # included. It is for a project whose comments are in another language; an empty one keeps the library's.

The classes are imported rather than read as text: the variable's name is an attribute's value, assembled by a call, and reading it from the source would mean performing that call yourself.

A rule of your own

A rule is a class with four fields and a run, declared through entry points. There is no need to fork the library:

# myproject_checks/_no_print.py
import ast
from collections.abc import Iterator
from typing import ClassVar, Final

from py_checks.config import CheckSettings
from py_checks.core import ParsedFile, Scope, Violation

CODE: Final = "no-print"


class NoPrint:
    """Fails if a `print` was left in the source."""

    code: ClassVar[str] = CODE
    Settings: ClassVar[type[CheckSettings]] = CheckSettings
    scope: ClassVar[Scope] = Scope.FILE
    marker: ClassVar[str] = "# my-ok"

    @classmethod
    def run(cls, *, file: ParsedFile, settings: CheckSettings) -> Iterator[Violation]:
        for node in ast.walk(file.tree):
            if isinstance(node, ast.Call) and getattr(node.func, "id", "") == "print":
                yield Violation.from_node(
                    node=node,
                    path=file.path,
                    code=CODE,
                    message="a print in the source; an event is written to the log",
                )

[project.entry-points."py_checks.checks"]
no-print = "myproject_checks:NoPrint"

From there it behaves like a native one: it appears in list and explain, obeys ignore, and is lifted by a mark.

Commands

Development

uv sync
uv run pre-commit install
uv run pytest -q

A check is described by folders of examples rather than by a test: tests/checks/<code>/ with ok/ and bad/ inside, and syrupy compares the snapshot of the output. Project rules have tests/projects/<code>__<variant>/. The library checks itself: a rule that cannot survive its own repository has no business reaching anybody else's.

The repository's own conventions are in AGENTS.md.

License

MIT — © 2026 Armontex.