python-checks 0.5.0__tar.gz → 0.7.0__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 (171) hide show
  1. {python_checks-0.5.0 → python_checks-0.7.0}/PKG-INFO +4 -1
  2. {python_checks-0.5.0 → python_checks-0.7.0}/README.md +1 -0
  3. {python_checks-0.5.0 → python_checks-0.7.0}/pyproject.toml +4 -1
  4. {python_checks-0.5.0 → python_checks-0.7.0}/pyproject.toml.orig +8 -1
  5. python_checks-0.7.0/src/py_checks/checks/__init__.py +21 -0
  6. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/_kind.py +34 -32
  7. python_checks-0.7.0/src/py_checks/checks/_layout.py +267 -0
  8. python_checks-0.7.0/src/py_checks/checks/_location.py +181 -0
  9. python_checks-0.7.0/src/py_checks/checks/_names.py +88 -0
  10. python_checks-0.7.0/src/py_checks/checks/api/__init__.py +18 -0
  11. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/api/_edge_declarations.py +80 -73
  12. python_checks-0.7.0/src/py_checks/checks/api/_marker.py +5 -0
  13. python_checks-0.7.0/src/py_checks/checks/calls/__init__.py +13 -0
  14. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/calls/_confined_functions.py +15 -14
  15. python_checks-0.7.0/src/py_checks/checks/calls/_marker.py +5 -0
  16. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/database/__init__.py +7 -5
  17. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/database/_bound_checks.py +32 -31
  18. python_checks-0.7.0/src/py_checks/checks/database/_confined_calls.py +118 -0
  19. python_checks-0.7.0/src/py_checks/checks/database/_marker.py +5 -0
  20. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/database/_model_boundary.py +37 -36
  21. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/database/_model_columns.py +36 -36
  22. python_checks-0.7.0/src/py_checks/checks/database/_raw_sql.py +111 -0
  23. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/database/_schema_drift.py +50 -47
  24. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/database/_statement_keys.py +29 -28
  25. python_checks-0.7.0/src/py_checks/checks/effects/__init__.py +20 -0
  26. python_checks-0.7.0/src/py_checks/checks/effects/_determinism.py +108 -0
  27. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/effects/_log_events.py +18 -18
  28. python_checks-0.7.0/src/py_checks/checks/effects/_marker.py +5 -0
  29. python_checks-0.7.0/src/py_checks/checks/errors/__init__.py +10 -0
  30. python_checks-0.7.0/src/py_checks/checks/errors/_marker.py +5 -0
  31. python_checks-0.7.0/src/py_checks/checks/errors/_refusals.py +160 -0
  32. python_checks-0.7.0/src/py_checks/checks/hygiene/__init__.py +15 -0
  33. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/hygiene/_dependency_bounds.py +33 -33
  34. python_checks-0.7.0/src/py_checks/checks/hygiene/_marker.py +5 -0
  35. python_checks-0.7.0/src/py_checks/checks/imports/__init__.py +25 -0
  36. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/imports/_confined.py +15 -14
  37. python_checks-0.7.0/src/py_checks/checks/imports/_marker.py +7 -0
  38. python_checks-0.7.0/src/py_checks/checks/imports/_sealed.py +89 -0
  39. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/imports/_statements.py +5 -5
  40. python_checks-0.7.0/src/py_checks/checks/placement/__init__.py +35 -0
  41. python_checks-0.7.0/src/py_checks/checks/placement/_class_modules.py +93 -0
  42. python_checks-0.7.0/src/py_checks/checks/placement/_class_placement.py +81 -0
  43. python_checks-0.7.0/src/py_checks/checks/placement/_marker.py +7 -0
  44. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/placement/_operation_shape.py +140 -77
  45. python_checks-0.7.0/src/py_checks/checks/placement/_required_class.py +207 -0
  46. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/signatures/__init__.py +6 -5
  47. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/signatures/_function_length.py +18 -17
  48. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/signatures/_functions.py +13 -12
  49. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/signatures/_keyword_only.py +23 -21
  50. python_checks-0.7.0/src/py_checks/checks/signatures/_marker.py +7 -0
  51. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/signatures/_module_length.py +8 -8
  52. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/signatures/_nesting.py +20 -20
  53. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/signatures/_signature_layout.py +46 -47
  54. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/types/__init__.py +5 -4
  55. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/types/_annotation_shapes.py +20 -20
  56. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/types/_config_fields.py +44 -43
  57. python_checks-0.7.0/src/py_checks/checks/types/_confined_types.py +129 -0
  58. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/types/_constant_annotations.py +18 -17
  59. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/checks/types/_frozen_dataclasses.py +14 -13
  60. python_checks-0.7.0/src/py_checks/checks/types/_marker.py +5 -0
  61. python_checks-0.7.0/src/py_checks/cli/__init__.py +10 -0
  62. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/cli/_app.py +3 -3
  63. python_checks-0.7.0/src/py_checks/cli/_protocols.py +20 -0
  64. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/cli/commands/__init__.py +6 -4
  65. python_checks-0.7.0/src/py_checks/cli/commands/_doctor.py +329 -0
  66. python_checks-0.7.0/src/py_checks/cli/commands/_explain.py +65 -0
  67. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/cli/commands/_list.py +10 -10
  68. python_checks-0.7.0/src/py_checks/cli/commands/_mutation.py +247 -0
  69. python_checks-0.7.0/src/py_checks/cli/commands/_run.py +166 -0
  70. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/cli/commands/_summary.py +3 -3
  71. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/cli/commands/_sync.py +9 -9
  72. python_checks-0.7.0/src/py_checks/config/__init__.py +32 -0
  73. python_checks-0.7.0/src/py_checks/config/_base.py +35 -0
  74. python_checks-0.7.0/src/py_checks/config/_config.py +147 -0
  75. python_checks-0.7.0/src/py_checks/config/_constants.py +31 -0
  76. python_checks-0.7.0/src/py_checks/config/_errors.py +12 -0
  77. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/config/_loader.py +22 -21
  78. python_checks-0.7.0/src/py_checks/config/_toml.py +25 -0
  79. python_checks-0.7.0/src/py_checks/contracts/__init__.py +26 -0
  80. python_checks-0.7.0/src/py_checks/contracts/_constants.py +21 -0
  81. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/contracts/_layout.py +7 -6
  82. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/contracts/_render.py +80 -31
  83. python_checks-0.7.0/src/py_checks/contracts/_settings.py +43 -0
  84. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/__init__.py +4 -4
  85. python_checks-0.7.0/src/py_checks/core/_constants.py +16 -0
  86. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/_discovery.py +6 -6
  87. python_checks-0.7.0/src/py_checks/core/_edit.py +95 -0
  88. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/_errors.py +4 -4
  89. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/_fixer.py +5 -5
  90. python_checks-0.7.0/src/py_checks/core/_format.py +30 -0
  91. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/_markers.py +41 -37
  92. python_checks-0.7.0/src/py_checks/core/_paths.py +51 -0
  93. python_checks-0.7.0/src/py_checks/core/_protocols.py +103 -0
  94. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/_registry.py +15 -13
  95. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/_report.py +8 -7
  96. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/_runner.py +18 -18
  97. python_checks-0.7.0/src/py_checks/core/_settings.py +44 -0
  98. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/core/_source.py +14 -13
  99. python_checks-0.7.0/src/py_checks/core/_violation.py +75 -0
  100. python_checks-0.7.0/src/py_checks/environment/__init__.py +14 -0
  101. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/environment/_constants.py +1 -1
  102. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/environment/_render.py +38 -37
  103. python_checks-0.7.0/src/py_checks/environment/_settings.py +41 -0
  104. python_checks-0.7.0/src/py_checks/mutation/__init__.py +34 -0
  105. python_checks-0.7.0/src/py_checks/mutation/_baseline.py +47 -0
  106. python_checks-0.7.0/src/py_checks/mutation/_constants.py +11 -0
  107. python_checks-0.7.0/src/py_checks/mutation/_errors.py +12 -0
  108. python_checks-0.7.0/src/py_checks/mutation/_gate.py +175 -0
  109. python_checks-0.7.0/src/py_checks/mutation/_mutmut.py +162 -0
  110. python_checks-0.7.0/src/py_checks/mutation/_process.py +44 -0
  111. python_checks-0.7.0/src/py_checks/mutation/_scope.py +155 -0
  112. python_checks-0.7.0/src/py_checks/mutation/_settings.py +54 -0
  113. python_checks-0.7.0/src/py_checks/sync/__init__.py +16 -0
  114. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/sync/_sync.py +11 -10
  115. python_checks-0.5.0/src/py_checks/checks/__init__.py +0 -20
  116. python_checks-0.5.0/src/py_checks/checks/_layout.py +0 -239
  117. python_checks-0.5.0/src/py_checks/checks/_location.py +0 -139
  118. python_checks-0.5.0/src/py_checks/checks/_names.py +0 -86
  119. python_checks-0.5.0/src/py_checks/checks/api/__init__.py +0 -18
  120. python_checks-0.5.0/src/py_checks/checks/api/_marker.py +0 -5
  121. python_checks-0.5.0/src/py_checks/checks/calls/__init__.py +0 -13
  122. python_checks-0.5.0/src/py_checks/checks/calls/_marker.py +0 -5
  123. python_checks-0.5.0/src/py_checks/checks/database/_confined_calls.py +0 -118
  124. python_checks-0.5.0/src/py_checks/checks/database/_marker.py +0 -5
  125. python_checks-0.5.0/src/py_checks/checks/database/_raw_sql.py +0 -108
  126. python_checks-0.5.0/src/py_checks/checks/effects/__init__.py +0 -19
  127. python_checks-0.5.0/src/py_checks/checks/effects/_determinism.py +0 -105
  128. python_checks-0.5.0/src/py_checks/checks/effects/_marker.py +0 -5
  129. python_checks-0.5.0/src/py_checks/checks/errors/__init__.py +0 -10
  130. python_checks-0.5.0/src/py_checks/checks/errors/_marker.py +0 -5
  131. python_checks-0.5.0/src/py_checks/checks/errors/_refusals.py +0 -159
  132. python_checks-0.5.0/src/py_checks/checks/hygiene/__init__.py +0 -14
  133. python_checks-0.5.0/src/py_checks/checks/hygiene/_marker.py +0 -5
  134. python_checks-0.5.0/src/py_checks/checks/imports/__init__.py +0 -25
  135. python_checks-0.5.0/src/py_checks/checks/imports/_marker.py +0 -7
  136. python_checks-0.5.0/src/py_checks/checks/imports/_sealed.py +0 -100
  137. python_checks-0.5.0/src/py_checks/checks/placement/__init__.py +0 -35
  138. python_checks-0.5.0/src/py_checks/checks/placement/_class_modules.py +0 -81
  139. python_checks-0.5.0/src/py_checks/checks/placement/_class_placement.py +0 -79
  140. python_checks-0.5.0/src/py_checks/checks/placement/_marker.py +0 -7
  141. python_checks-0.5.0/src/py_checks/checks/placement/_required_class.py +0 -164
  142. python_checks-0.5.0/src/py_checks/checks/signatures/_marker.py +0 -7
  143. python_checks-0.5.0/src/py_checks/checks/types/_confined_types.py +0 -129
  144. python_checks-0.5.0/src/py_checks/checks/types/_marker.py +0 -5
  145. python_checks-0.5.0/src/py_checks/cli/__init__.py +0 -10
  146. python_checks-0.5.0/src/py_checks/cli/_protocols.py +0 -19
  147. python_checks-0.5.0/src/py_checks/cli/commands/_doctor.py +0 -293
  148. python_checks-0.5.0/src/py_checks/cli/commands/_explain.py +0 -64
  149. python_checks-0.5.0/src/py_checks/cli/commands/_run.py +0 -167
  150. python_checks-0.5.0/src/py_checks/config/__init__.py +0 -32
  151. python_checks-0.5.0/src/py_checks/config/_base.py +0 -34
  152. python_checks-0.5.0/src/py_checks/config/_config.py +0 -144
  153. python_checks-0.5.0/src/py_checks/config/_constants.py +0 -31
  154. python_checks-0.5.0/src/py_checks/config/_errors.py +0 -12
  155. python_checks-0.5.0/src/py_checks/config/_toml.py +0 -24
  156. python_checks-0.5.0/src/py_checks/contracts/__init__.py +0 -26
  157. python_checks-0.5.0/src/py_checks/contracts/_constants.py +0 -18
  158. python_checks-0.5.0/src/py_checks/contracts/_settings.py +0 -41
  159. python_checks-0.5.0/src/py_checks/core/_constants.py +0 -15
  160. python_checks-0.5.0/src/py_checks/core/_edit.py +0 -92
  161. python_checks-0.5.0/src/py_checks/core/_format.py +0 -30
  162. python_checks-0.5.0/src/py_checks/core/_paths.py +0 -49
  163. python_checks-0.5.0/src/py_checks/core/_protocols.py +0 -99
  164. python_checks-0.5.0/src/py_checks/core/_settings.py +0 -44
  165. python_checks-0.5.0/src/py_checks/core/_violation.py +0 -73
  166. python_checks-0.5.0/src/py_checks/environment/__init__.py +0 -14
  167. python_checks-0.5.0/src/py_checks/environment/_settings.py +0 -40
  168. python_checks-0.5.0/src/py_checks/sync/__init__.py +0 -16
  169. {python_checks-0.5.0 → python_checks-0.7.0}/LICENSE +0 -0
  170. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/__init__.py +0 -0
  171. {python_checks-0.5.0 → python_checks-0.7.0}/src/py_checks/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: python-checks
3
- Version: 0.5.0
3
+ Version: 0.7.0
4
4
  Summary: Проверки архитектурных соглашений проекта
5
5
  Author: Armontex
6
6
  Author-email: Armontex <windle1337@gmail.com>
@@ -11,12 +11,14 @@ Requires-Dist: pydantic>=2.13.5,<3
11
11
  Requires-Dist: pydantic-settings>=2.15.0,<3
12
12
  Requires-Dist: rich>=14.0.0,<16.0.0
13
13
  Requires-Dist: typer>=0.27.2,<0.28
14
+ Requires-Dist: mutmut>=3.7,<4 ; extra == 'mutation'
14
15
  Requires-Python: >=3.14
15
16
  Project-URL: Homepage, https://github.com/Armontex/py-checks
16
17
  Project-URL: Source, https://github.com/Armontex/py-checks
17
18
  Project-URL: Issues, https://github.com/Armontex/py-checks/issues
18
19
  Project-URL: Changelog, https://github.com/Armontex/py-checks/blob/main/CHANGELOG.md
19
20
  Project-URL: Documentation, https://github.com/Armontex/py-checks/blob/main/docs/service.md
21
+ Provides-Extra: mutation
20
22
  Description-Content-Type: text/markdown
21
23
 
22
24
  <div align="center">
@@ -351,6 +353,7 @@ obeys `ignore`, and is lifted by a mark.
351
353
  | `py-checks explain <code>` | what a rule asks for and what it can be told |
352
354
  | `py-checks sync [--check]` | build the import contracts and `.env.example` |
353
355
  | `py-checks doctor` | check the config itself: typos, dead addresses, rules that say nothing |
356
+ | `py-checks mutation diff\|full\|record` | the mutation gate over `mutmut`; needs `python-checks[mutation]` |
354
357
 
355
358
  ## Development
356
359
 
@@ -330,6 +330,7 @@ obeys `ignore`, and is lifted by a mark.
330
330
  | `py-checks explain <code>` | what a rule asks for and what it can be told |
331
331
  | `py-checks sync [--check]` | build the import contracts and `.env.example` |
332
332
  | `py-checks doctor` | check the config itself: typos, dead addresses, rules that say nothing |
333
+ | `py-checks mutation diff\|full\|record` | the mutation gate over `mutmut`; needs `python-checks[mutation]` |
333
334
 
334
335
  ## Development
335
336
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.5.0"
3
+ version = "0.7.0"
4
4
  description = "Проверки архитектурных соглашений проекта"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -25,6 +25,9 @@ Issues = "https://github.com/Armontex/py-checks/issues"
25
25
  Changelog = "https://github.com/Armontex/py-checks/blob/main/CHANGELOG.md"
26
26
  Documentation = "https://github.com/Armontex/py-checks/blob/main/docs/service.md"
27
27
 
28
+ [project.optional-dependencies]
29
+ mutation = ["mutmut>=3.7,<4"]
30
+
28
31
  [project.scripts]
29
32
  py-checks = "py_checks.cli:main"
30
33
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.5.0"
3
+ version = "0.7.0"
4
4
  description = "Проверки архитектурных соглашений проекта"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -28,6 +28,13 @@ Issues = "https://github.com/Armontex/py-checks/issues"
28
28
  Changelog = "https://github.com/Armontex/py-checks/blob/main/CHANGELOG.md"
29
29
  Documentation = "https://github.com/Armontex/py-checks/blob/main/docs/service.md"
30
30
 
31
+ [project.optional-dependencies]
32
+ # Мутационный гейт зовёт mutmut процессом и читает то, что тот напечатал:
33
+ # импорта нет, а договор есть — формат вывода. Потолок на следующем мажоре
34
+ # потому, что в мажоре этот формат и поменяют, а разбор, промахнувшийся мимо
35
+ # строк `survived`, насчитал бы ноль выживших и пропустил бы всё.
36
+ mutation = ["mutmut>=3.7,<4"]
37
+
31
38
  [project.scripts]
32
39
  py-checks = "py_checks.cli:main"
33
40
 
@@ -0,0 +1,21 @@
1
+ """The rule implementations, one package per group.
2
+
3
+ Inside a group, one module per check. Rules that moved to import-linter, ruff
4
+ and alembic are not carried over here; what went where is written down in
5
+ `docs/current.md`.
6
+
7
+ A check is one class, and everything it reads the tree with lives inside it:
8
+ helpers do not spread across the module, and it is clear whose they are. A
9
+ leaf takes `@staticmethod`; a helper that calls another helper takes
10
+ `@classmethod`, so it calls through `cls` rather than by the class's name.
11
+
12
+ Inside the class lives what belongs to the rule. A word of the language does
13
+ not belong to a rule: "what is this node called" is `_names.py`, "where does
14
+ this file lie" is `_location.py`, "what is declared here" is `_kind.py`. Six
15
+ identical `_name` across classes are not six helpers but one, forgotten in six
16
+ places.
17
+
18
+ The word that lifts a rule from the code is declared once per group, in the
19
+ package's `_marker.py`. It lifts any check of the group; to lift exactly one,
20
+ there is `# check-ok: <code>: <reason>`.
21
+ """
@@ -1,8 +1,8 @@
1
- """Что объявлено в модуле: класс, порт, dataclass, алиас.
1
+ """What a module declares: a class, a port, a dataclass, an alias.
2
2
 
3
- Правила размещения говорят о видах объявлений, а не о синтаксисе: «в `dto/`
4
- лежат dataclass-ы», «в `ports/` — протоколы». Вид узнаётся один раз здесь, и
5
- этим же знанием пользуются все правила группы.
3
+ The placement rules speak of kinds of declaration, not of syntax: "`dto/` holds
4
+ dataclasses", "`ports/` holds protocols". The kind is recognised once, here,
5
+ and every rule of the group uses the same knowledge.
6
6
  """
7
7
 
8
8
  from __future__ import annotations
@@ -27,12 +27,12 @@ ENUMS: Final[frozenset[str]] = frozenset(
27
27
 
28
28
  ERROR_BASES: Final[frozenset[str]] = frozenset({"Exception", "BaseException"})
29
29
 
30
- # Исключение проекта наследуется от своего же корня (`class NotFound(DomainError)`),
31
- # а не от `Exception`, — но имя корня кончается так же, и по нему вид узнаётся,
32
- # не читая чужой модуль.
30
+ # A project's exception inherits from its own root (`class NotFound(DomainError)`),
31
+ # not from `Exception` — but the root's name ends the same way, and the kind is
32
+ # recognised by it without reading another module.
33
33
  ERROR_SUFFIXES: Final[tuple[str, ...]] = ("Error", "Exception")
34
34
 
35
- # Присваивание, которым объявляют имя для типа, а не значение.
35
+ # An assignment that declares a name for a type, not a value.
36
36
  ALIAS_ANNOTATION: Final = "TypeAlias"
37
37
  ALIAS_FACTORIES: Final[frozenset[str]] = frozenset(
38
38
  {"TypeVar", "NewType", "ParamSpec", "TypeAliasType"},
@@ -54,7 +54,7 @@ ALIAS_CONSTRUCTORS: Final[frozenset[str]] = frozenset(
54
54
 
55
55
 
56
56
  class Kind(StrEnum):
57
- """Виды объявлений, о которых говорят правила размещения."""
57
+ """The kinds of declaration the placement rules speak of."""
58
58
 
59
59
  CLASS = "class"
60
60
  PORT = "port"
@@ -67,29 +67,29 @@ class Kind(StrEnum):
67
67
 
68
68
  @property
69
69
  def said(self) -> str:
70
- """Как вид называется в сообщении: `str.title` занят самим `str`."""
70
+ """What the kind is called in a message: `str.title` is taken by `str` itself."""
71
71
  return NAMES[self]
72
72
 
73
73
 
74
74
  NAMES: Final[dict[Kind, str]] = {
75
- Kind.CLASS: "класс",
76
- Kind.PORT: "порт",
75
+ Kind.CLASS: "class",
76
+ Kind.PORT: "port",
77
77
  Kind.DATACLASS: "dataclass",
78
- Kind.MODEL: "модель",
79
- Kind.ALIAS: "алиас",
80
- Kind.ENUM: "перечисление",
81
- Kind.ERROR: "исключение",
82
- Kind.FUNCTION: "функция",
78
+ Kind.MODEL: "model",
79
+ Kind.ALIAS: "alias",
80
+ Kind.ENUM: "enum",
81
+ Kind.ERROR: "exception",
82
+ Kind.FUNCTION: "function",
83
83
  }
84
84
 
85
85
 
86
86
  @dataclass(frozen=True, slots=True)
87
87
  class Declaration:
88
- """Объявление верхнего уровня: имя, вид и узел.
88
+ """A top-level declaration: the name, the kind and the node.
89
89
 
90
- `kind` пуст, когда вид по одному файлу не виден: класс с базой из другого
91
- модуля. Имя у такого всё равно есть, и правило, которое смотрит на суффикс,
92
- им пользуется.
90
+ `kind` is empty when one file does not show the kind: a class with a base
91
+ from another module. Such a class still has a name, and a rule that looks at
92
+ the suffix uses it.
93
93
  """
94
94
 
95
95
  name: str
@@ -98,10 +98,11 @@ class Declaration:
98
98
 
99
99
 
100
100
  def declarations(*, tree: ast.Module) -> Iterator[Declaration]:
101
- """Всё, что модуль объявляет.
101
+ """Everything a module declares.
102
102
 
103
- Импорты, константы, блоки `if TYPE_CHECKING` и докстринг сюда не попадают:
104
- они разрешены везде, и правилам размещения о них говорить нечего.
103
+ Imports, constants, `if TYPE_CHECKING` blocks and the docstring are left
104
+ out: they are allowed everywhere, and the placement rules have nothing to
105
+ say about them.
105
106
  """
106
107
  for node in tree.body:
107
108
  match node:
@@ -129,12 +130,12 @@ def declarations(*, tree: ast.Module) -> Iterator[Declaration]:
129
130
 
130
131
 
131
132
  def _class(*, node: ast.ClassDef) -> Kind | None:
132
- """Вид класса; `None`, если по одному файлу его не видно.
133
+ """The class's kind; `None` if one file does not show it.
133
134
 
134
- База, объявленная в другом модуле, — это вид, которого отсюда не видно:
135
- `class CodeMismatchResponse(ErrorResponse)` — pydantic-модель, но узнать
136
- это можно только прочитав тот модуль. Про такой класс правило молчит:
137
- заблудившийся хелпер, ради которого оно написано, базы обычно не имеет.
135
+ A base declared in another module is a kind that cannot be seen from here:
136
+ `class CodeMismatchResponse(ErrorResponse)` is a pydantic model, but that
137
+ can only be learned by reading that module. The rule is silent about such
138
+ a class: the stray helper it was written for usually has no base.
138
139
  """
139
140
  bases = frozenset(names(nodes=node.bases))
140
141
  if bases & ABSTRACT or _metaclass(node=node):
@@ -164,10 +165,11 @@ def _metaclass(*, node: ast.ClassDef) -> bool:
164
165
 
165
166
 
166
167
  def _alias(*, node: ast.AnnAssign | ast.Assign) -> bool:
167
- """Присваивание, объявляющее имя для типа.
168
+ """An assignment that declares a name for a type.
168
169
 
169
- Три вида: с аннотацией `TypeAlias`, вызов фабрики вроде `NewType`, и голое
170
- `Row = dict[str, int]` — имя для формы, а не значение.
170
+ Three kinds: annotated with `TypeAlias`, a call of a factory such as
171
+ `NewType`, and a bare `Row = dict[str, int]` — a name for a shape, not a
172
+ value.
171
173
  """
172
174
  if isinstance(node, ast.AnnAssign) and name(node=node.annotation) == ALIAS_ANNOTATION:
173
175
  return True
@@ -0,0 +1,267 @@
1
+ """The project's layout: one block per directory.
2
+
3
+ Four rules speak of the same thing from four sides: what may lie here
4
+ (`class-modules`), what lives only here (`class-placement`), what a module must
5
+ declare (`required-class`) and what shape an operation has here
6
+ (`operation-shape`). Each used to have a table of its own, and one fact about
7
+ `use_cases` had to be written four times in four syntaxes, stitched together
8
+ by eye on a string key.
9
+
10
+ Now there is one block per directory, and the rules read their own columns
11
+ from it:
12
+
13
+ ```toml
14
+ [layout."application/use_cases"]
15
+ only = ["class"]
16
+ suffix = "UseCase"
17
+ required = true
18
+ operation = { method = "execute", max-arguments = 3 }
19
+ ```
20
+
21
+ The rules still know nothing of each other — they simply read one table. The
22
+ address in the heading is looked for as consecutive path parts, so
23
+ `application/use_cases` is found in a modular service too, where the path
24
+ starts with `modules/<name>/`, and `*` matches any one part.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ from dataclasses import dataclass
30
+ from enum import StrEnum
31
+ from typing import TYPE_CHECKING, Final, Self
32
+
33
+ from pydantic import Field, model_validator
34
+
35
+ from py_checks.checks._kind import Kind
36
+ from py_checks.config import CheckSettings
37
+
38
+ if TYPE_CHECKING:
39
+ from collections.abc import Iterable
40
+
41
+ from py_checks.checks._kind import Declaration
42
+ from py_checks.checks._location import Place
43
+
44
+ SECTION: Final = "layout"
45
+
46
+
47
+ class Orm(StrEnum):
48
+ """What a directory is to an ORM model.
49
+
50
+ The model's home and the place where it is built are two ends of one
51
+ convention, and writing them in a separate table would name the same two
52
+ directories a second time: the layout already knows them by name.
53
+ """
54
+
55
+ # Models are declared here: anywhere else it is a table nobody expects at
56
+ # that address, and alembic's autogenerate sees only their package.
57
+ DECLARED = "declared"
58
+
59
+ # Models are built here: building a model means writing a row.
60
+ BUILT = "built"
61
+
62
+
63
+ class Operation(CheckSettings):
64
+ """The shape of an operation kept in this directory.
65
+
66
+ `method` is the only public door: a use case is asked for one thing, and a
67
+ second public method means a second operation sharing a constructor with
68
+ the first. Empty means the number of doors is not limited: a module's
69
+ service has as many as its entity has transitions.
70
+
71
+ `forbids` is the names of types an operation does not hold: `UnitOfWork` is
72
+ caught both as `IPlacementUnitOfWork` and as `UnitOfWorkFactory`, because
73
+ what is forbidden is holding the transaction, not spelling its name one
74
+ particular way.
75
+
76
+ `max_arguments` is how many arguments the entrance takes. A door carries
77
+ what came from outside, and an entrance longer than a few fields is a thing
78
+ with a name: a command, a query, a DTO.
79
+
80
+ `takes` is the suffix of what the entrance takes: `Query` in
81
+ `use_cases/queries` means every argument of the door is a `...Query`. The
82
+ split into commands and queries holds only while each side is handed its
83
+ own kind of input.
84
+ """
85
+
86
+ method: str | None = None
87
+ forbids: tuple[str, ...] = ()
88
+ max_arguments: int | None = Field(
89
+ default=None,
90
+ gt=0,
91
+ )
92
+ takes: str | None = None
93
+
94
+
95
+ class Directory(CheckSettings):
96
+ """What the project keeps in this directory.
97
+
98
+ `only` — the kinds that belong here, and nothing else sits beside them.
99
+ Written out empty, `only = []`, it means constants and nothing else;
100
+ left unset, it restricts nothing.
101
+ `home` — the kinds that belong ONLY here: a port declared at the other end
102
+ of the tree is a port the reader will not find.
103
+ `area` — the part of the tree within which home and name mean anything at
104
+ all: the rule about `dto` is written about the application layer, and a
105
+ dataclass in the bootstrap or in observability is just a way to put three
106
+ fields side by side.
107
+ `suffix` — what the class this directory exists for is called; it too
108
+ lives only here.
109
+ `required` — a module must declare such a class, first and alone.
110
+ `named` — every class of the `only` kinds here ends with `suffix`, as many
111
+ per module as the idea needs: `domain/value_objects` keeps `PriceValue`
112
+ and `CurrencyValue` side by side, and a bare `Price` beside them is the
113
+ one the reader will not recognise.
114
+ `operation` — the shape of an operation, if operations are kept here.
115
+ `orm` — what the directory is to an ORM model: its home or where it is built.
116
+ `base` — the base class by which a model is recognised in the models' home.
117
+ """
118
+
119
+ only: tuple[Kind, ...] = ()
120
+ home: tuple[Kind, ...] = ()
121
+ area: str | None = None
122
+ suffix: str | None = None
123
+ required: bool = False
124
+ named: bool = False
125
+ operation: Operation | None = None
126
+ orm: Orm | None = None
127
+ base: str | None = None
128
+
129
+ @property
130
+ def restricted(self) -> bool:
131
+ """Whether `only` was written: an empty list written out allows constants alone."""
132
+ return bool(self.only) or "only" in self.model_fields_set
133
+
134
+ @model_validator(mode="after")
135
+ def _named(self) -> Self:
136
+ """Obligation and shape rest on the name: without a suffix there is no checking them."""
137
+ if self.suffix is not None:
138
+ return self
139
+ if self.required:
140
+ message = "`required` without `suffix`: it is unclear which class must be there"
141
+ raise ValueError(message)
142
+ if self.named:
143
+ message = "`named` without `suffix`: it is unclear what the classes are called"
144
+ raise ValueError(message)
145
+ if self.operation is not None:
146
+ message = (
147
+ "`operation` without `suffix`: it is unclear which class is the operation here"
148
+ )
149
+ raise ValueError(message)
150
+ return self
151
+
152
+ @model_validator(mode="after")
153
+ def _claims(self) -> Self:
154
+ """An area narrows a claim: without a home and a name there is nothing to narrow."""
155
+ if self.area is not None and not self.home and self.suffix is None:
156
+ message = "`area` without `home` and `suffix`: this directory claims nothing"
157
+ raise ValueError(message)
158
+ return self
159
+
160
+ @model_validator(mode="after")
161
+ def _declares(self) -> Self:
162
+ """`base` is about the models' home: where they are built, there is nothing to spot."""
163
+ if self.base is not None and self.orm is not Orm.DECLARED:
164
+ message = '`base` without `orm = "declared"`: the base is named by the models\' home'
165
+ raise ValueError(message)
166
+ return self
167
+
168
+
169
+ class Layout(CheckSettings):
170
+ """The `[layout]` section: a directory's address — and a block about it.
171
+
172
+ The keys come from the project, so the model accepts any: directory names
173
+ are data, not fields. What is checked is the content of the block.
174
+ """
175
+
176
+ model_config = CheckSettings.model_config | {"extra": "allow"}
177
+
178
+ # pydantic's typed `extra`: the key is an address, the value a block.
179
+ __pydantic_extra__: dict[str, Directory] # type: ignore[assignment]
180
+
181
+ @property
182
+ def directories(self) -> dict[str, Directory]:
183
+ return self.__pydantic_extra__
184
+
185
+
186
+ def addressed(
187
+ *,
188
+ layout: dict[str, Directory],
189
+ orm: Orm,
190
+ ) -> tuple[str, ...]:
191
+ """The addresses that declared themselves this end of the ORM model convention."""
192
+ return tuple(address for address, directory in layout.items() if directory.orm is orm)
193
+
194
+
195
+ def innermost(
196
+ *,
197
+ where: Place,
198
+ among: Iterable[tuple[str, Directory]],
199
+ ) -> tuple[str, Directory] | None:
200
+ """The block of the innermost matched directory.
201
+
202
+ The deepest wins: `modules/betslip/application/services` beats
203
+ `application`. At equal depth, the longer address: a path says more about a
204
+ place than one name.
205
+ """
206
+ matched = [
207
+ (depth, len(address), address, directory)
208
+ for address, directory in among
209
+ if (depth := where.reach(address=address)) is not None
210
+ ]
211
+ if not matched:
212
+ return None
213
+ deepest = max(matched, key=lambda found: found[:2])
214
+ return deepest[2], deepest[3]
215
+
216
+
217
+ @dataclass(frozen=True, slots=True)
218
+ class Claim:
219
+ """Whose home this is and why the declaration asks to be in it."""
220
+
221
+ address: str
222
+ said: str
223
+
224
+
225
+ def claimants(
226
+ *,
227
+ declared: Declaration,
228
+ layout: dict[str, Directory],
229
+ where: Place,
230
+ ) -> list[Claim]:
231
+ """The addresses that claim this declaration: by name or by kind.
232
+
233
+ A block with `area` claims only what lies inside the named part of the
234
+ tree: the convention about `dto` is written about the application layer,
235
+ and a dataclass in the bootstrap is not its to judge.
236
+ """
237
+ found: list[Claim] = []
238
+ for address, directory in layout.items():
239
+ if directory.area is not None and not where.holds(path=directory.area):
240
+ continue
241
+ said = _claim(
242
+ declared=declared,
243
+ directory=directory,
244
+ )
245
+ if said is not None:
246
+ found.append(
247
+ Claim(
248
+ address=address,
249
+ said=said,
250
+ )
251
+ )
252
+ return found
253
+
254
+
255
+ def _claim(
256
+ *,
257
+ declared: Declaration,
258
+ directory: Directory,
259
+ ) -> str | None:
260
+ """Why this address claims the declaration; `None` — it does not."""
261
+ if directory.suffix is not None and declared.name.endswith(directory.suffix):
262
+ return f"ends with {directory.suffix}"
263
+ if declared.kind is not None and declared.kind in directory.home:
264
+ said = declared.kind.said
265
+ # Every kind's name is a plain English noun, so the first letter decides.
266
+ return f"is {'an' if said[0] in 'aeiou' else 'a'} {said}"
267
+ return None