python-checks 0.3.0__tar.gz → 0.3.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- python_checks-0.3.2/PKG-INFO +370 -0
- python_checks-0.3.2/README.md +349 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/pyproject.toml +8 -1
- {python_checks-0.3.0 → python_checks-0.3.2}/pyproject.toml.orig +11 -1
- python_checks-0.3.0/PKG-INFO +0 -342
- python_checks-0.3.0/README.md +0 -326
- {python_checks-0.3.0 → python_checks-0.3.2}/LICENSE +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/_kind.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/_location.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/_names.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/api/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/api/_endpoint_declarations.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/api/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/calls/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/calls/_confined_functions.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/calls/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_bound_checks.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_confined_calls.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_model_boundary.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_model_columns.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_raw_sql.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_schema_drift.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_statement_keys.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/effects/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/effects/_determinism.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/effects/_log_events.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/effects/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/hygiene/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/hygiene/_dependency_bounds.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/hygiene/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/_confined.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/_sealed.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/_statements.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_class_modules.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_class_placement.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_operation_shape.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_required_class.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_function_length.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_functions.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_keyword_only.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_module_length.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_nesting.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_signature_layout.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_annotation_shapes.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_config_fields.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_confined_types.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_constant_annotations.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_frozen_dataclasses.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_marker.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/_app.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/_protocols.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_explain.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_list.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_run.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_summary.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_sync.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_base.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_config.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_constants.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_errors.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_loader.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_toml.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/_constants.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/_layout.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/_render.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/_settings.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_constants.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_discovery.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_edit.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_errors.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_fixer.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_format.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_markers.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_protocols.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_registry.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_report.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_runner.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_settings.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_source.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_violation.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/environment/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/environment/_constants.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/environment/_render.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/environment/_settings.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/py.typed +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/sync/__init__.py +0 -0
- {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/sync/_sync.py +0 -0
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: python-checks
|
|
3
|
+
Version: 0.3.2
|
|
4
|
+
Summary: Проверки архитектурных соглашений проекта
|
|
5
|
+
Author: Armontex
|
|
6
|
+
Author-email: Armontex <windle1337@gmail.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Dist: libcst>=1.9,<2
|
|
10
|
+
Requires-Dist: pydantic>=2.13.5,<3
|
|
11
|
+
Requires-Dist: pydantic-settings>=2.15.0,<3
|
|
12
|
+
Requires-Dist: rich>=14.0.0,<16.0.0
|
|
13
|
+
Requires-Dist: typer>=0.27.2,<0.28
|
|
14
|
+
Requires-Python: >=3.14
|
|
15
|
+
Project-URL: Homepage, https://github.com/Armontex/py-checks
|
|
16
|
+
Project-URL: Source, https://github.com/Armontex/py-checks
|
|
17
|
+
Project-URL: Issues, https://github.com/Armontex/py-checks/issues
|
|
18
|
+
Project-URL: Changelog, https://github.com/Armontex/py-checks/blob/main/CHANGELOG.md
|
|
19
|
+
Project-URL: Documentation, https://github.com/Armontex/py-checks/blob/main/docs/service.md
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
<div align="center">
|
|
23
|
+
|
|
24
|
+
<img src="docs/logo.svg" width="112" alt="py-checks">
|
|
25
|
+
|
|
26
|
+
# py-checks
|
|
27
|
+
|
|
28
|
+
**Your project's architecture, checked like code.**
|
|
29
|
+
|
|
30
|
+
English · [Русский](docs/readmes/README.ru.md)
|
|
31
|
+
|
|
32
|
+
[](https://github.com/Armontex/py-checks/actions/workflows/ci.yml)
|
|
33
|
+
[](https://www.python.org/)
|
|
34
|
+
[](#what-is-checked)
|
|
35
|
+
[](#pre-commit)
|
|
36
|
+
[](https://docs.astral.sh/ruff/)
|
|
37
|
+
[](https://microsoft.github.io/pyright/)
|
|
38
|
+
[](https://github.com/Armontex/py-checks/blob/main/LICENSE)
|
|
39
|
+
|
|
40
|
+
</div>
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
A linter knows the language; it does not know your project. It will not tell
|
|
45
|
+
you that an ORM model has wandered into a use case, that a `Numeric` column
|
|
46
|
+
was left without a CHECK, that `datetime.now()` is called in the domain rather
|
|
47
|
+
than behind a port. These are not language errors — they are broken
|
|
48
|
+
conventions, and until now review caught them: by eye, differently for each
|
|
49
|
+
reviewer, from scratch every time.
|
|
50
|
+
|
|
51
|
+
`py-checks` is an engine for conventions like these. The library brings the
|
|
52
|
+
rules, the project brings its architecture: the names of the layers, the list
|
|
53
|
+
of sealed zones, where the ORM lives, what bounds a column. Without the
|
|
54
|
+
project's tables the rules stay silent — the library does not guess what your
|
|
55
|
+
domain is called.
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
src/app/modules/cashout/application/offer.py:34:9: determinism: uuid4() is not deterministic;
|
|
59
|
+
the identifier is handed out at the edge and passed inwards
|
|
60
|
+
src/app/infra/database/models/bet.py:51:5: model-columns: stake is a Numeric with no bound;
|
|
61
|
+
money is described by Numeric(18, 4)
|
|
62
|
+
src/app/presentation/api/v1/routers/bets.py:22:1: endpoint-declarations: POST /bets
|
|
63
|
+
did not name a response_model
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Why
|
|
67
|
+
|
|
68
|
+
- **A convention stops being spoken.** The rule is written once, with its
|
|
69
|
+
reason, and checked on every commit — rather than recalled at review by
|
|
70
|
+
whoever remembers it.
|
|
71
|
+
- **The rule is universal, the table is yours.** One rule, "this call lives
|
|
72
|
+
only here", covers both the transaction boundary and the ban on `float` in
|
|
73
|
+
the domain. The library contains not one name from your project.
|
|
74
|
+
- **A refusal explains itself.** The message says what is wrong and what to
|
|
75
|
+
write instead, not "violation of rule #14".
|
|
76
|
+
- **An exemption costs one line and owes a reason.**
|
|
77
|
+
`# check-ok: raw-sql: a liveness probe, there is no ORM form of it` — a mark
|
|
78
|
+
without a reason is itself a violation.
|
|
79
|
+
- **We do not do other people's work.** What ruff, pyright and import-linter
|
|
80
|
+
can do stays theirs; what was handed over, and why, is written down in
|
|
81
|
+
[`docs/service.md`](https://github.com/Armontex/py-checks/blob/main/docs/service.md).
|
|
82
|
+
|
|
83
|
+
## Install
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
uv add --dev python-checks
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Installed as `python-checks`, called as `py-checks`: a neighbour holds the
|
|
90
|
+
short name on PyPI, while the command, the settings section and the package
|
|
91
|
+
stayed as they were.
|
|
92
|
+
|
|
93
|
+
Needs Python 3.14+. Dependencies: `libcst`, `pydantic`, `pydantic-settings`,
|
|
94
|
+
`rich`, `typer`.
|
|
95
|
+
|
|
96
|
+
## In a minute
|
|
97
|
+
|
|
98
|
+
Put a `py-checks.toml` next to `pyproject.toml`:
|
|
99
|
+
|
|
100
|
+
```toml
|
|
101
|
+
src = "src"
|
|
102
|
+
|
|
103
|
+
[module-length]
|
|
104
|
+
max-lines = 300
|
|
105
|
+
|
|
106
|
+
# Rules that depend on place only work in the zones you name.
|
|
107
|
+
[model-columns]
|
|
108
|
+
zones = ["infra/database/models"]
|
|
109
|
+
types = { Numeric = "money is described by Numeric(18, 4)" }
|
|
110
|
+
|
|
111
|
+
[determinism]
|
|
112
|
+
zones = ["modules/*/domain", "modules/*/application"]
|
|
113
|
+
sources = { "datetime.now" = "take the clock as a port", "uuid4" = "hand the id out at the edge" }
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
and run:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
py-checks run # check `src`
|
|
120
|
+
py-checks run --fix # and repair what repairs itself
|
|
121
|
+
py-checks list # which rules exist and which are on
|
|
122
|
+
py-checks explain determinism # what a rule asks for and what it can be told
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
The settings can also live in a `[tool.py-checks]` section of
|
|
126
|
+
`pyproject.toml` — but one of the two: two places at once is an error to this
|
|
127
|
+
library, not a merge.
|
|
128
|
+
|
|
129
|
+
## What is checked
|
|
130
|
+
|
|
131
|
+
Twenty-eight rules in nine groups:
|
|
132
|
+
|
|
133
|
+
| Group | About |
|
|
134
|
+
|---|---|
|
|
135
|
+
| `imports` | which package is allowed where, which zone is sealed |
|
|
136
|
+
| `placement` | what belongs in this directory and how an operation is shaped |
|
|
137
|
+
| `signatures` | module length, nesting depth, the shape of a signature |
|
|
138
|
+
| `types` | bounds on fields, the shape of an annotation, immutability |
|
|
139
|
+
| `database` | the model's boundary, a column's material, the shape of a query, the schema |
|
|
140
|
+
| `effects` | the clock, the dice, and the name of an event in the log |
|
|
141
|
+
| `api` | what a route answers with and what it must declare |
|
|
142
|
+
| `calls` | a function whose call sites can be listed |
|
|
143
|
+
| `hygiene` | a ceiling on a dependency |
|
|
144
|
+
|
|
145
|
+
<details>
|
|
146
|
+
<summary>All twenty-eight</summary>
|
|
147
|
+
|
|
148
|
+
| Code | What fails | Scope |
|
|
149
|
+
|---|---|:-:|
|
|
150
|
+
| `confined-imports` | a package is imported outside the places set aside for it | file |
|
|
151
|
+
| `sealed-imports` | a sealed zone imports a foreign package | file |
|
|
152
|
+
| `class-modules` | a module holds what its directory does not allow | file |
|
|
153
|
+
| `class-placement` | a class lies somewhere other than where its kind lives | file |
|
|
154
|
+
| `operation-shape` | an operation is not shaped like an operation | file |
|
|
155
|
+
| `required-class` | a module did not declare the class its directory exists for | file |
|
|
156
|
+
| `keyword-only-arguments` | a signature is not written out in full | file |
|
|
157
|
+
| `function-length` | a function is longer than the limit | file |
|
|
158
|
+
| `module-length` | a module is longer than the limit | file |
|
|
159
|
+
| `nesting` | control structures are nested deeper than the limit | file |
|
|
160
|
+
| `signature-layout` | a list of two or more entries is written on one line | file |
|
|
161
|
+
| `annotation-shapes` | a shape is named such that its fields have no names | file |
|
|
162
|
+
| `config-fields` | a settings field carries no bound | file |
|
|
163
|
+
| `confined-types` | a field in this part of the tree is declared with a type banned here | file |
|
|
164
|
+
| `constant-annotations` | a constant did not say by its type that it is one | file |
|
|
165
|
+
| `frozen-dataclasses` | a dataclass in a zone is declared without the required arguments | file |
|
|
166
|
+
| `bound-checks` | a bounded column did not restate its bound as a CHECK | file |
|
|
167
|
+
| `confined-calls` | a named method was called somewhere it does not belong | file |
|
|
168
|
+
| `model-boundary` | an ORM model is declared, built or handed out in the wrong place | file |
|
|
169
|
+
| `model-columns` | a column is built out of the wrong material | file |
|
|
170
|
+
| `raw-sql` | SQL is written as a string where an expression would do | file |
|
|
171
|
+
| `statement-keys` | a statement names a column by string, or goes to the database in a loop | file |
|
|
172
|
+
| `schema-drift` | the models and the migrations describe different schemas | environment |
|
|
173
|
+
| `determinism` | the code reads the clock, the dice or a new identifier itself | file |
|
|
174
|
+
| `log-events` | an event in the log is named by something other than an enum member | file |
|
|
175
|
+
| `endpoint-declarations` | a route did not say what it answers with | file |
|
|
176
|
+
| `confined-functions` | a named function was called from somewhere it may not be | file |
|
|
177
|
+
| `dependency-bounds` | a dependency may move to a version nobody has ever run | project |
|
|
178
|
+
|
|
179
|
+
</details>
|
|
180
|
+
|
|
181
|
+
Every rule explains itself in full — `py-checks explain <code>` prints the
|
|
182
|
+
docstring with the reason and the list of settings. A worked set of tables for
|
|
183
|
+
a typical service is in
|
|
184
|
+
[`docs/service.md`](https://github.com/Armontex/py-checks/blob/main/docs/service.md).
|
|
185
|
+
|
|
186
|
+
### Three kinds of rule
|
|
187
|
+
|
|
188
|
+
What a rule is handed to judge, the rule declares itself, in its `scope`:
|
|
189
|
+
|
|
190
|
+
- **file** — a parsed source file; most rules are these;
|
|
191
|
+
- **project** — the root: the manifest, the agreement of the repository's files with one another;
|
|
192
|
+
- **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.
|
|
193
|
+
|
|
194
|
+
## Marks
|
|
195
|
+
|
|
196
|
+
A line can be taken out of a rule's judgement, but you have to say why:
|
|
197
|
+
|
|
198
|
+
```python
|
|
199
|
+
text("SELECT 1") # db-ok: raw-sql: a liveness probe, there is no ORM form of it
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The canonical form is `# check-ok: <code>: <reason>`, and it lifts exactly one
|
|
203
|
+
rule. Every group has a short word of its own (`# db-ok`, `# type-ok`,
|
|
204
|
+
`# signature-ok`, …): a person remembers the group, not twenty-eight codes.
|
|
205
|
+
|
|
206
|
+
A line may carry several marks — a signature written in a column gathers them
|
|
207
|
+
on its last line:
|
|
208
|
+
|
|
209
|
+
```python
|
|
210
|
+
) -> object: # signature-ok: this is how pydantic calls it # type-ok: raw input
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
A mark with no code, with a typo in the code, or with no reason is a violation
|
|
214
|
+
itself. A silently dead mark looks like a disabled check, while the check is in
|
|
215
|
+
fact running and simply does not see it.
|
|
216
|
+
|
|
217
|
+
## pre-commit
|
|
218
|
+
|
|
219
|
+
```yaml
|
|
220
|
+
- repo: https://github.com/Armontex/py-checks
|
|
221
|
+
rev: v0.3.1
|
|
222
|
+
hooks:
|
|
223
|
+
- id: py-checks
|
|
224
|
+
args: [--fix] # repair what repairs itself
|
|
225
|
+
- id: py-checks-sync # contracts and `.env.example` rebuilt
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
One hook rather than one per rule: which rules run is the config's decision. A
|
|
229
|
+
set of rules is called with `args: [--select, "<code>,<code>"]`; a repeated
|
|
230
|
+
flag does the same.
|
|
231
|
+
|
|
232
|
+
It has to stand **before** `ruff-format`: the autofix writes characters, not
|
|
233
|
+
columns, and the project's formatter lays the signature out.
|
|
234
|
+
|
|
235
|
+
Everything else — ruff, pyright, import-linter, commitizen — the project
|
|
236
|
+
declares itself: each has a hook written by its own authors.
|
|
237
|
+
|
|
238
|
+
## Import contracts
|
|
239
|
+
|
|
240
|
+
The project's layers are described once, and `.importlinter` is built from
|
|
241
|
+
that:
|
|
242
|
+
|
|
243
|
+
```toml
|
|
244
|
+
[contracts.layers]
|
|
245
|
+
domain = ["domain"]
|
|
246
|
+
application = ["application", "domain"]
|
|
247
|
+
presentation = ["presentation", "application"]
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
py-checks sync # build
|
|
252
|
+
py-checks sync --check # fail if the file has fallen behind
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
It is built not only from the table but from what is on disk: a layer that
|
|
256
|
+
does not exist is left out of the contract — otherwise import-linter would
|
|
257
|
+
fail on the first module that is not there. The graph itself is walked by
|
|
258
|
+
import-linter's own hook.
|
|
259
|
+
|
|
260
|
+
The header of the built file can be your own — `header` in `[contracts]`,
|
|
261
|
+
`#` included; as with `.env.example`, it is for a project whose comments are
|
|
262
|
+
in another language.
|
|
263
|
+
|
|
264
|
+
## The environment example
|
|
265
|
+
|
|
266
|
+
The name of a variable is known to the settings field — it declares it as
|
|
267
|
+
`validation_alias`, and `config-fields` watches for that. So `.env.example` is
|
|
268
|
+
derived from the same classes the variables are read into, and there is no
|
|
269
|
+
reason to keep it by hand: it falls out of step silently, and that is noticed
|
|
270
|
+
when the variable turns out to be missing in production.
|
|
271
|
+
|
|
272
|
+
```toml
|
|
273
|
+
[env-example]
|
|
274
|
+
settings = ["myservice.config.settings:Settings"]
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
The same `py-checks sync` builds it alongside the contracts. The root class is
|
|
278
|
+
enough: it has already listed its sections as its own fields, and repeating
|
|
279
|
+
that list in the settings would mean keeping a second one that drifts from the
|
|
280
|
+
first. A section field does not become a variable — it has no name of its own
|
|
281
|
+
in the environment. What goes into the file is the variable's name, its
|
|
282
|
+
default, the first paragraph of the class docstring and the field's
|
|
283
|
+
`description` if it has one — so the explanation lives next to the field
|
|
284
|
+
rather than in a file that outlives it.
|
|
285
|
+
|
|
286
|
+
The header can be written by the project as well — `header = "# Generated by
|
|
287
|
+
py-checks."`, `#` included. It is for a project whose comments are in another
|
|
288
|
+
language; an empty one keeps the library's.
|
|
289
|
+
|
|
290
|
+
The classes are imported rather than read as text: the variable's name is an
|
|
291
|
+
attribute's value, assembled by a call, and reading it from the source would
|
|
292
|
+
mean performing that call yourself.
|
|
293
|
+
|
|
294
|
+
## A rule of your own
|
|
295
|
+
|
|
296
|
+
A rule is a class with four fields and a `run`, declared through entry points.
|
|
297
|
+
There is no need to fork the library:
|
|
298
|
+
|
|
299
|
+
```python
|
|
300
|
+
# myproject_checks/_no_print.py
|
|
301
|
+
import ast
|
|
302
|
+
from collections.abc import Iterator
|
|
303
|
+
from typing import ClassVar, Final
|
|
304
|
+
|
|
305
|
+
from py_checks.config import CheckSettings
|
|
306
|
+
from py_checks.core import ParsedFile, Scope, Violation
|
|
307
|
+
|
|
308
|
+
CODE: Final = "no-print"
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
class NoPrint:
|
|
312
|
+
"""Fails if a `print` was left in the source."""
|
|
313
|
+
|
|
314
|
+
code: ClassVar[str] = CODE
|
|
315
|
+
Settings: ClassVar[type[CheckSettings]] = CheckSettings
|
|
316
|
+
scope: ClassVar[Scope] = Scope.FILE
|
|
317
|
+
marker: ClassVar[str] = "# my-ok"
|
|
318
|
+
|
|
319
|
+
@classmethod
|
|
320
|
+
def run(cls, *, file: ParsedFile, settings: CheckSettings) -> Iterator[Violation]:
|
|
321
|
+
for node in ast.walk(file.tree):
|
|
322
|
+
if isinstance(node, ast.Call) and getattr(node.func, "id", "") == "print":
|
|
323
|
+
yield Violation.from_node(
|
|
324
|
+
node=node,
|
|
325
|
+
path=file.path,
|
|
326
|
+
code=CODE,
|
|
327
|
+
message="a print in the source; an event is written to the log",
|
|
328
|
+
)
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
```toml
|
|
332
|
+
[project.entry-points."py_checks.checks"]
|
|
333
|
+
no-print = "myproject_checks:NoPrint"
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
From there it behaves like a native one: it appears in `list` and `explain`,
|
|
337
|
+
obeys `ignore`, and is lifted by a mark.
|
|
338
|
+
|
|
339
|
+
## Commands
|
|
340
|
+
|
|
341
|
+
| Command | |
|
|
342
|
+
|---|---|
|
|
343
|
+
| `py-checks run [paths]` | run the checks; `0` — clean, `1` — violations found |
|
|
344
|
+
| `py-checks run --fix` | apply the repairs that are unambiguous |
|
|
345
|
+
| `py-checks run --select <code>,<code>` | only the named rules, `ignore` notwithstanding |
|
|
346
|
+
| `py-checks run --all` | including the rules that need a live environment |
|
|
347
|
+
| `py-checks list` | every rule: code, state, one line of description |
|
|
348
|
+
| `py-checks explain <code>` | what a rule asks for and what it can be told |
|
|
349
|
+
| `py-checks sync [--check]` | build the import contracts and `.env.example` |
|
|
350
|
+
|
|
351
|
+
## Development
|
|
352
|
+
|
|
353
|
+
```bash
|
|
354
|
+
uv sync
|
|
355
|
+
uv run pre-commit install
|
|
356
|
+
uv run pytest -q
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
A check is described by folders of examples rather than by a test:
|
|
360
|
+
`tests/checks/<code>/` with `ok/` and `bad/` inside, and syrupy compares the
|
|
361
|
+
snapshot of the output. Project rules have `tests/projects/<code>__<variant>/`.
|
|
362
|
+
The library checks itself: a rule that cannot survive its own repository has
|
|
363
|
+
no business reaching anybody else's.
|
|
364
|
+
|
|
365
|
+
The repository's own conventions are in
|
|
366
|
+
[`AGENTS.md`](https://github.com/Armontex/py-checks/blob/main/AGENTS.md).
|
|
367
|
+
|
|
368
|
+
## License
|
|
369
|
+
|
|
370
|
+
[MIT](https://github.com/Armontex/py-checks/blob/main/LICENSE) — © 2026 Armontex.
|