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.
Files changed (103) hide show
  1. python_checks-0.3.2/PKG-INFO +370 -0
  2. python_checks-0.3.2/README.md +349 -0
  3. {python_checks-0.3.0 → python_checks-0.3.2}/pyproject.toml +8 -1
  4. {python_checks-0.3.0 → python_checks-0.3.2}/pyproject.toml.orig +11 -1
  5. python_checks-0.3.0/PKG-INFO +0 -342
  6. python_checks-0.3.0/README.md +0 -326
  7. {python_checks-0.3.0 → python_checks-0.3.2}/LICENSE +0 -0
  8. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/__init__.py +0 -0
  9. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/__init__.py +0 -0
  10. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/_kind.py +0 -0
  11. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/_location.py +0 -0
  12. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/_names.py +0 -0
  13. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/api/__init__.py +0 -0
  14. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/api/_endpoint_declarations.py +0 -0
  15. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/api/_marker.py +0 -0
  16. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/calls/__init__.py +0 -0
  17. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/calls/_confined_functions.py +0 -0
  18. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/calls/_marker.py +0 -0
  19. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/__init__.py +0 -0
  20. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_bound_checks.py +0 -0
  21. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_confined_calls.py +0 -0
  22. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_marker.py +0 -0
  23. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_model_boundary.py +0 -0
  24. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_model_columns.py +0 -0
  25. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_raw_sql.py +0 -0
  26. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_schema_drift.py +0 -0
  27. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/database/_statement_keys.py +0 -0
  28. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/effects/__init__.py +0 -0
  29. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/effects/_determinism.py +0 -0
  30. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/effects/_log_events.py +0 -0
  31. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/effects/_marker.py +0 -0
  32. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/hygiene/__init__.py +0 -0
  33. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/hygiene/_dependency_bounds.py +0 -0
  34. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/hygiene/_marker.py +0 -0
  35. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/__init__.py +0 -0
  36. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/_confined.py +0 -0
  37. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/_marker.py +0 -0
  38. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/_sealed.py +0 -0
  39. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/imports/_statements.py +0 -0
  40. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/__init__.py +0 -0
  41. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_class_modules.py +0 -0
  42. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_class_placement.py +0 -0
  43. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_marker.py +0 -0
  44. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_operation_shape.py +0 -0
  45. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/placement/_required_class.py +0 -0
  46. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/__init__.py +0 -0
  47. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_function_length.py +0 -0
  48. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_functions.py +0 -0
  49. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_keyword_only.py +0 -0
  50. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_marker.py +0 -0
  51. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_module_length.py +0 -0
  52. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_nesting.py +0 -0
  53. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/signatures/_signature_layout.py +0 -0
  54. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/__init__.py +0 -0
  55. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_annotation_shapes.py +0 -0
  56. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_config_fields.py +0 -0
  57. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_confined_types.py +0 -0
  58. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_constant_annotations.py +0 -0
  59. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_frozen_dataclasses.py +0 -0
  60. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/checks/types/_marker.py +0 -0
  61. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/__init__.py +0 -0
  62. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/_app.py +0 -0
  63. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/_protocols.py +0 -0
  64. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/__init__.py +0 -0
  65. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_explain.py +0 -0
  66. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_list.py +0 -0
  67. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_run.py +0 -0
  68. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_summary.py +0 -0
  69. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/cli/commands/_sync.py +0 -0
  70. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/__init__.py +0 -0
  71. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_base.py +0 -0
  72. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_config.py +0 -0
  73. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_constants.py +0 -0
  74. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_errors.py +0 -0
  75. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_loader.py +0 -0
  76. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/config/_toml.py +0 -0
  77. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/__init__.py +0 -0
  78. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/_constants.py +0 -0
  79. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/_layout.py +0 -0
  80. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/_render.py +0 -0
  81. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/contracts/_settings.py +0 -0
  82. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/__init__.py +0 -0
  83. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_constants.py +0 -0
  84. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_discovery.py +0 -0
  85. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_edit.py +0 -0
  86. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_errors.py +0 -0
  87. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_fixer.py +0 -0
  88. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_format.py +0 -0
  89. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_markers.py +0 -0
  90. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_protocols.py +0 -0
  91. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_registry.py +0 -0
  92. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_report.py +0 -0
  93. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_runner.py +0 -0
  94. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_settings.py +0 -0
  95. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_source.py +0 -0
  96. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/core/_violation.py +0 -0
  97. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/environment/__init__.py +0 -0
  98. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/environment/_constants.py +0 -0
  99. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/environment/_render.py +0 -0
  100. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/environment/_settings.py +0 -0
  101. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/py.typed +0 -0
  102. {python_checks-0.3.0 → python_checks-0.3.2}/src/py_checks/sync/__init__.py +0 -0
  103. {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
+ [![ci](https://github.com/Armontex/py-checks/actions/workflows/ci.yml/badge.svg)](https://github.com/Armontex/py-checks/actions/workflows/ci.yml)
33
+ [![python](https://img.shields.io/badge/python-3.14%2B-3776AB)](https://www.python.org/)
34
+ [![checks](https://img.shields.io/badge/checks-28-2ea043)](#what-is-checked)
35
+ [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-FAB040)](#pre-commit)
36
+ [![ruff](https://img.shields.io/badge/linted%20with-ruff-261230)](https://docs.astral.sh/ruff/)
37
+ [![pyright](https://img.shields.io/badge/types-pyright%20strict-1f6feb)](https://microsoft.github.io/pyright/)
38
+ [![license](https://img.shields.io/badge/license-MIT-750014)](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.