python-checks 0.5.0__tar.gz → 0.6.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 (169) hide show
  1. {python_checks-0.5.0 → python_checks-0.6.0}/PKG-INFO +4 -1
  2. {python_checks-0.5.0 → python_checks-0.6.0}/README.md +1 -0
  3. {python_checks-0.5.0 → python_checks-0.6.0}/pyproject.toml +4 -1
  4. {python_checks-0.5.0 → python_checks-0.6.0}/pyproject.toml.orig +8 -1
  5. python_checks-0.6.0/src/py_checks/checks/__init__.py +21 -0
  6. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/_kind.py +34 -32
  7. python_checks-0.6.0/src/py_checks/checks/_layout.py +246 -0
  8. python_checks-0.6.0/src/py_checks/checks/_location.py +161 -0
  9. python_checks-0.6.0/src/py_checks/checks/_names.py +88 -0
  10. python_checks-0.6.0/src/py_checks/checks/api/__init__.py +18 -0
  11. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/api/_edge_declarations.py +80 -73
  12. python_checks-0.6.0/src/py_checks/checks/api/_marker.py +5 -0
  13. python_checks-0.6.0/src/py_checks/checks/calls/__init__.py +13 -0
  14. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/calls/_confined_functions.py +15 -14
  15. python_checks-0.6.0/src/py_checks/checks/calls/_marker.py +5 -0
  16. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/database/__init__.py +7 -5
  17. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/database/_bound_checks.py +32 -31
  18. python_checks-0.6.0/src/py_checks/checks/database/_confined_calls.py +118 -0
  19. python_checks-0.6.0/src/py_checks/checks/database/_marker.py +5 -0
  20. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/database/_model_boundary.py +37 -36
  21. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/database/_model_columns.py +36 -36
  22. python_checks-0.6.0/src/py_checks/checks/database/_raw_sql.py +111 -0
  23. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/database/_schema_drift.py +50 -47
  24. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/database/_statement_keys.py +29 -28
  25. python_checks-0.6.0/src/py_checks/checks/effects/__init__.py +20 -0
  26. python_checks-0.6.0/src/py_checks/checks/effects/_determinism.py +108 -0
  27. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/effects/_log_events.py +18 -18
  28. python_checks-0.6.0/src/py_checks/checks/effects/_marker.py +5 -0
  29. python_checks-0.6.0/src/py_checks/checks/errors/__init__.py +10 -0
  30. python_checks-0.6.0/src/py_checks/checks/errors/_marker.py +5 -0
  31. python_checks-0.6.0/src/py_checks/checks/errors/_refusals.py +160 -0
  32. python_checks-0.6.0/src/py_checks/checks/hygiene/__init__.py +15 -0
  33. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/hygiene/_dependency_bounds.py +33 -33
  34. python_checks-0.6.0/src/py_checks/checks/hygiene/_marker.py +5 -0
  35. python_checks-0.6.0/src/py_checks/checks/imports/__init__.py +25 -0
  36. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/imports/_confined.py +15 -14
  37. python_checks-0.6.0/src/py_checks/checks/imports/_marker.py +7 -0
  38. python_checks-0.6.0/src/py_checks/checks/imports/_sealed.py +89 -0
  39. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/imports/_statements.py +5 -5
  40. python_checks-0.6.0/src/py_checks/checks/placement/__init__.py +35 -0
  41. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/placement/_class_modules.py +17 -15
  42. python_checks-0.6.0/src/py_checks/checks/placement/_class_placement.py +80 -0
  43. python_checks-0.6.0/src/py_checks/checks/placement/_marker.py +7 -0
  44. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/placement/_operation_shape.py +56 -54
  45. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/placement/_required_class.py +28 -28
  46. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/signatures/__init__.py +6 -5
  47. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/signatures/_function_length.py +18 -17
  48. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/signatures/_functions.py +13 -12
  49. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/signatures/_keyword_only.py +23 -21
  50. python_checks-0.6.0/src/py_checks/checks/signatures/_marker.py +7 -0
  51. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/signatures/_module_length.py +8 -8
  52. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/signatures/_nesting.py +20 -20
  53. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/signatures/_signature_layout.py +46 -47
  54. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/types/__init__.py +5 -4
  55. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/types/_annotation_shapes.py +20 -20
  56. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/types/_config_fields.py +44 -43
  57. python_checks-0.6.0/src/py_checks/checks/types/_confined_types.py +129 -0
  58. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/types/_constant_annotations.py +18 -17
  59. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/checks/types/_frozen_dataclasses.py +14 -13
  60. python_checks-0.6.0/src/py_checks/checks/types/_marker.py +5 -0
  61. python_checks-0.6.0/src/py_checks/cli/__init__.py +10 -0
  62. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/cli/_app.py +3 -3
  63. python_checks-0.6.0/src/py_checks/cli/_protocols.py +20 -0
  64. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/cli/commands/__init__.py +6 -4
  65. python_checks-0.6.0/src/py_checks/cli/commands/_doctor.py +307 -0
  66. python_checks-0.6.0/src/py_checks/cli/commands/_explain.py +65 -0
  67. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/cli/commands/_list.py +10 -10
  68. python_checks-0.6.0/src/py_checks/cli/commands/_mutation.py +247 -0
  69. python_checks-0.6.0/src/py_checks/cli/commands/_run.py +166 -0
  70. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/cli/commands/_summary.py +3 -3
  71. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/cli/commands/_sync.py +9 -9
  72. python_checks-0.6.0/src/py_checks/config/__init__.py +32 -0
  73. python_checks-0.6.0/src/py_checks/config/_base.py +35 -0
  74. python_checks-0.6.0/src/py_checks/config/_config.py +147 -0
  75. python_checks-0.6.0/src/py_checks/config/_constants.py +31 -0
  76. python_checks-0.6.0/src/py_checks/config/_errors.py +12 -0
  77. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/config/_loader.py +22 -21
  78. python_checks-0.6.0/src/py_checks/config/_toml.py +25 -0
  79. python_checks-0.6.0/src/py_checks/contracts/__init__.py +26 -0
  80. python_checks-0.6.0/src/py_checks/contracts/_constants.py +18 -0
  81. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/contracts/_layout.py +7 -6
  82. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/contracts/_render.py +26 -25
  83. python_checks-0.6.0/src/py_checks/contracts/_settings.py +41 -0
  84. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/__init__.py +4 -4
  85. python_checks-0.6.0/src/py_checks/core/_constants.py +16 -0
  86. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/_discovery.py +6 -6
  87. python_checks-0.6.0/src/py_checks/core/_edit.py +95 -0
  88. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/_errors.py +4 -4
  89. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/_fixer.py +5 -5
  90. python_checks-0.6.0/src/py_checks/core/_format.py +30 -0
  91. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/_markers.py +41 -37
  92. python_checks-0.6.0/src/py_checks/core/_paths.py +51 -0
  93. python_checks-0.6.0/src/py_checks/core/_protocols.py +103 -0
  94. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/_registry.py +15 -13
  95. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/_report.py +8 -7
  96. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/_runner.py +18 -18
  97. python_checks-0.6.0/src/py_checks/core/_settings.py +44 -0
  98. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/core/_source.py +14 -13
  99. python_checks-0.6.0/src/py_checks/core/_violation.py +75 -0
  100. python_checks-0.6.0/src/py_checks/environment/__init__.py +14 -0
  101. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/environment/_constants.py +1 -1
  102. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/environment/_render.py +38 -37
  103. python_checks-0.6.0/src/py_checks/environment/_settings.py +41 -0
  104. python_checks-0.6.0/src/py_checks/mutation/__init__.py +34 -0
  105. python_checks-0.6.0/src/py_checks/mutation/_baseline.py +47 -0
  106. python_checks-0.6.0/src/py_checks/mutation/_constants.py +11 -0
  107. python_checks-0.6.0/src/py_checks/mutation/_errors.py +12 -0
  108. python_checks-0.6.0/src/py_checks/mutation/_gate.py +175 -0
  109. python_checks-0.6.0/src/py_checks/mutation/_mutmut.py +162 -0
  110. python_checks-0.6.0/src/py_checks/mutation/_process.py +44 -0
  111. python_checks-0.6.0/src/py_checks/mutation/_scope.py +155 -0
  112. python_checks-0.6.0/src/py_checks/mutation/_settings.py +54 -0
  113. python_checks-0.6.0/src/py_checks/sync/__init__.py +16 -0
  114. {python_checks-0.5.0 → python_checks-0.6.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_placement.py +0 -79
  139. python_checks-0.5.0/src/py_checks/checks/placement/_marker.py +0 -7
  140. python_checks-0.5.0/src/py_checks/checks/signatures/_marker.py +0 -7
  141. python_checks-0.5.0/src/py_checks/checks/types/_confined_types.py +0 -129
  142. python_checks-0.5.0/src/py_checks/checks/types/_marker.py +0 -5
  143. python_checks-0.5.0/src/py_checks/cli/__init__.py +0 -10
  144. python_checks-0.5.0/src/py_checks/cli/_protocols.py +0 -19
  145. python_checks-0.5.0/src/py_checks/cli/commands/_doctor.py +0 -293
  146. python_checks-0.5.0/src/py_checks/cli/commands/_explain.py +0 -64
  147. python_checks-0.5.0/src/py_checks/cli/commands/_run.py +0 -167
  148. python_checks-0.5.0/src/py_checks/config/__init__.py +0 -32
  149. python_checks-0.5.0/src/py_checks/config/_base.py +0 -34
  150. python_checks-0.5.0/src/py_checks/config/_config.py +0 -144
  151. python_checks-0.5.0/src/py_checks/config/_constants.py +0 -31
  152. python_checks-0.5.0/src/py_checks/config/_errors.py +0 -12
  153. python_checks-0.5.0/src/py_checks/config/_toml.py +0 -24
  154. python_checks-0.5.0/src/py_checks/contracts/__init__.py +0 -26
  155. python_checks-0.5.0/src/py_checks/contracts/_constants.py +0 -18
  156. python_checks-0.5.0/src/py_checks/contracts/_settings.py +0 -41
  157. python_checks-0.5.0/src/py_checks/core/_constants.py +0 -15
  158. python_checks-0.5.0/src/py_checks/core/_edit.py +0 -92
  159. python_checks-0.5.0/src/py_checks/core/_format.py +0 -30
  160. python_checks-0.5.0/src/py_checks/core/_paths.py +0 -49
  161. python_checks-0.5.0/src/py_checks/core/_protocols.py +0 -99
  162. python_checks-0.5.0/src/py_checks/core/_settings.py +0 -44
  163. python_checks-0.5.0/src/py_checks/core/_violation.py +0 -73
  164. python_checks-0.5.0/src/py_checks/environment/__init__.py +0 -14
  165. python_checks-0.5.0/src/py_checks/environment/_settings.py +0 -40
  166. python_checks-0.5.0/src/py_checks/sync/__init__.py +0 -16
  167. {python_checks-0.5.0 → python_checks-0.6.0}/LICENSE +0 -0
  168. {python_checks-0.5.0 → python_checks-0.6.0}/src/py_checks/__init__.py +0 -0
  169. {python_checks-0.5.0 → python_checks-0.6.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.6.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.6.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.6.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,246 @@
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
+
81
+ method: str | None = None
82
+ forbids: tuple[str, ...] = ()
83
+ max_arguments: int | None = Field(
84
+ default=None,
85
+ gt=0,
86
+ )
87
+
88
+
89
+ class Directory(CheckSettings):
90
+ """What the project keeps in this directory.
91
+
92
+ `only` — the kinds that belong here, and nothing else sits beside them.
93
+ `home` — the kinds that belong ONLY here: a port declared at the other end
94
+ of the tree is a port the reader will not find.
95
+ `area` — the part of the tree within which home and name mean anything at
96
+ all: the rule about `dto` is written about the application layer, and a
97
+ dataclass in the bootstrap or in observability is just a way to put three
98
+ fields side by side.
99
+ `suffix` — what the class this directory exists for is called; it too
100
+ lives only here.
101
+ `required` — a module must declare such a class, first and alone.
102
+ `operation` — the shape of an operation, if operations are kept here.
103
+ `orm` — what the directory is to an ORM model: its home or where it is built.
104
+ `base` — the base class by which a model is recognised in the models' home.
105
+ """
106
+
107
+ only: tuple[Kind, ...] = ()
108
+ home: tuple[Kind, ...] = ()
109
+ area: str | None = None
110
+ suffix: str | None = None
111
+ required: bool = False
112
+ operation: Operation | None = None
113
+ orm: Orm | None = None
114
+ base: str | None = None
115
+
116
+ @model_validator(mode="after")
117
+ def _named(self) -> Self:
118
+ """Obligation and shape rest on the name: without a suffix there is no checking them."""
119
+ if self.suffix is not None:
120
+ return self
121
+ if self.required:
122
+ message = "`required` without `suffix`: it is unclear which class must be there"
123
+ raise ValueError(message)
124
+ if self.operation is not None:
125
+ message = (
126
+ "`operation` without `suffix`: it is unclear which class is the operation here"
127
+ )
128
+ raise ValueError(message)
129
+ return self
130
+
131
+ @model_validator(mode="after")
132
+ def _claims(self) -> Self:
133
+ """An area narrows a claim: without a home and a name there is nothing to narrow."""
134
+ if self.area is not None and not self.home and self.suffix is None:
135
+ message = "`area` without `home` and `suffix`: this directory claims nothing"
136
+ raise ValueError(message)
137
+ return self
138
+
139
+ @model_validator(mode="after")
140
+ def _declares(self) -> Self:
141
+ """`base` is about the models' home: where they are built, there is nothing to spot."""
142
+ if self.base is not None and self.orm is not Orm.DECLARED:
143
+ message = '`base` without `orm = "declared"`: the base is named by the models\' home'
144
+ raise ValueError(message)
145
+ return self
146
+
147
+
148
+ class Layout(CheckSettings):
149
+ """The `[layout]` section: a directory's address — and a block about it.
150
+
151
+ The keys come from the project, so the model accepts any: directory names
152
+ are data, not fields. What is checked is the content of the block.
153
+ """
154
+
155
+ model_config = CheckSettings.model_config | {"extra": "allow"}
156
+
157
+ # pydantic's typed `extra`: the key is an address, the value a block.
158
+ __pydantic_extra__: dict[str, Directory] # type: ignore[assignment]
159
+
160
+ @property
161
+ def directories(self) -> dict[str, Directory]:
162
+ return self.__pydantic_extra__
163
+
164
+
165
+ def addressed(
166
+ *,
167
+ layout: dict[str, Directory],
168
+ orm: Orm,
169
+ ) -> tuple[str, ...]:
170
+ """The addresses that declared themselves this end of the ORM model convention."""
171
+ return tuple(address for address, directory in layout.items() if directory.orm is orm)
172
+
173
+
174
+ def innermost(
175
+ *,
176
+ where: Place,
177
+ among: Iterable[tuple[str, Directory]],
178
+ ) -> tuple[str, Directory] | None:
179
+ """The block of the innermost matched directory.
180
+
181
+ The deepest wins: `modules/betslip/application/services` beats
182
+ `application`. At equal depth, the longer address: a path says more about a
183
+ place than one name.
184
+ """
185
+ matched = [
186
+ (depth, len(address), address, directory)
187
+ for address, directory in among
188
+ if (depth := where.within(directory=address)) is not None
189
+ ]
190
+ if not matched:
191
+ return None
192
+ deepest = max(matched, key=lambda found: found[:2])
193
+ return deepest[2], deepest[3]
194
+
195
+
196
+ @dataclass(frozen=True, slots=True)
197
+ class Claim:
198
+ """Whose home this is and why the declaration asks to be in it."""
199
+
200
+ address: str
201
+ said: str
202
+
203
+
204
+ def claimants(
205
+ *,
206
+ declared: Declaration,
207
+ layout: dict[str, Directory],
208
+ where: Place,
209
+ ) -> list[Claim]:
210
+ """The addresses that claim this declaration: by name or by kind.
211
+
212
+ A block with `area` claims only what lies inside the named part of the
213
+ tree: the convention about `dto` is written about the application layer,
214
+ and a dataclass in the bootstrap is not its to judge.
215
+ """
216
+ found: list[Claim] = []
217
+ for address, directory in layout.items():
218
+ if directory.area is not None and not where.holds(path=directory.area):
219
+ continue
220
+ said = _claim(
221
+ declared=declared,
222
+ directory=directory,
223
+ )
224
+ if said is not None:
225
+ found.append(
226
+ Claim(
227
+ address=address,
228
+ said=said,
229
+ )
230
+ )
231
+ return found
232
+
233
+
234
+ def _claim(
235
+ *,
236
+ declared: Declaration,
237
+ directory: Directory,
238
+ ) -> str | None:
239
+ """Why this address claims the declaration; `None` — it does not."""
240
+ if directory.suffix is not None and declared.name.endswith(directory.suffix):
241
+ return f"ends with {directory.suffix}"
242
+ if declared.kind is not None and declared.kind in directory.home:
243
+ said = declared.kind.said
244
+ # Every kind's name is a plain English noun, so the first letter decides.
245
+ return f"is {'an' if said[0] in 'aeiou' else 'a'} {said}"
246
+ return None
@@ -0,0 +1,161 @@
1
+ """Where a file lies inside its package.
2
+
3
+ A rule about imports speaks of a place: "sqlalchemy lives in `infra/database`".
4
+ The place is counted from the source root, which the core knows from the
5
+ settings. It cannot be guessed from `__init__.py`: a directory without one
6
+ turns up in the middle of a package too — in one of the services half the
7
+ repositories lie that way.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from dataclasses import dataclass
13
+ from typing import TYPE_CHECKING, Final
14
+
15
+ from py_checks.config import CheckSettings
16
+ from py_checks.core import ANY, depth
17
+
18
+ if TYPE_CHECKING:
19
+ from collections.abc import Iterable
20
+ from pathlib import Path
21
+
22
+ from py_checks.core import ParsedFile
23
+
24
+ INIT: Final = "__init__"
25
+
26
+ SEPARATOR: Final = "/"
27
+
28
+ # A package and at least one step inside it: a file lying right in the source
29
+ # root is in no package, and there is nothing to say about its place.
30
+ INSIDE: Final = 2
31
+
32
+
33
+ @dataclass(frozen=True, slots=True)
34
+ class Place:
35
+ """A file's root package, its address inside it and the directories it lies in.
36
+
37
+ The directories are kept apart from the address because a zone is a
38
+ directory: `domain` means `domain/` and what is under it, not a module
39
+ that happens to be called `domain.py` in `application/exceptions/`. The
40
+ file's own name answers only to `*`: `domain/*` still takes
41
+ `domain/exceptions.py`, since `*` is any piece and a module is one.
42
+ """
43
+
44
+ package: str
45
+ parts: tuple[str, ...]
46
+ directories: tuple[str, ...]
47
+
48
+ @property
49
+ def where(self) -> str:
50
+ return "/".join(self.parts)
51
+
52
+ def under(self, *, prefix: str) -> bool:
53
+ """Whether the file lies under this path; an empty path allows nothing."""
54
+ if not prefix:
55
+ return False
56
+ wanted = tuple(prefix.split(SEPARATOR))
57
+ return self.parts[: len(wanted)] == wanted
58
+
59
+ def inside(self, *, zones: Iterable[str]) -> bool:
60
+ """Whether the file lies in at least one of these zones.
61
+
62
+ Only directories count; the file's own name matches `*` and nothing
63
+ else. Zones add up rather than argue: a rule works where it was asked
64
+ to, and is silent everywhere else.
65
+ """
66
+ return any(
67
+ depth(
68
+ parts=self.parts if zone.split(SEPARATOR)[-1] == ANY else self.directories,
69
+ path=zone,
70
+ )
71
+ is not None
72
+ for zone in zones
73
+ )
74
+
75
+ def anywhere(self, *, zones: Iterable[str]) -> bool:
76
+ """Whether the file is at one of these addresses, a directory or a module."""
77
+ return any(self.holds(path=zone) for zone in zones)
78
+
79
+ def holds(self, *, path: str) -> bool:
80
+ """Whether these address parts run in a row anywhere inside it.
81
+
82
+ The address includes the module's name, so `exceptions` matches both as
83
+ a directory and as the file `exceptions.py`: to the refusal vocabulary
84
+ it is one and the same place.
85
+ """
86
+ return (
87
+ depth(
88
+ parts=self.parts,
89
+ path=path,
90
+ )
91
+ is not None
92
+ )
93
+
94
+ def within(self, *, directory: str) -> int | None:
95
+ """Where the deepest occurrence of these directories ends, or `None`.
96
+
97
+ The file's name does not count: this is about a directory, not a
98
+ module. The end rather than the start, because the nesting of two keys
99
+ of different length can only be compared by where they end — the one
100
+ that ends later is deeper.
101
+ """
102
+ return depth(
103
+ parts=self.parts[:-1],
104
+ path=directory,
105
+ )
106
+
107
+
108
+ class ZonedSettings(CheckSettings):
109
+ """The settings of a rule that does not work everywhere.
110
+
111
+ `zones` are the places where the rule judges; an empty list means the rule
112
+ is silent. Silent, not judging everywhere: a convention about repositories
113
+ is wrong for use cases, and a rule whose zone was forgotten had better say
114
+ nothing than say something untrue across the whole tree.
115
+ """
116
+
117
+ zones: tuple[str, ...] = ()
118
+
119
+
120
+ def zoned(
121
+ *,
122
+ file: ParsedFile,
123
+ zones: Iterable[str],
124
+ ) -> Place | None:
125
+ """The file's address if it is in one of the zones; otherwise `None`: nothing to say."""
126
+ where = place(file=file)
127
+ if where is None or not where.inside(zones=zones):
128
+ return None
129
+ return where
130
+
131
+
132
+ def place(*, file: ParsedFile) -> Place | None:
133
+ """The file's address; `None` if the source root is unknown or the file is outside it."""
134
+ if file.source is None:
135
+ return None
136
+ relative = _relative(
137
+ path=file.path,
138
+ source=file.source,
139
+ )
140
+ if relative is None or len(relative) < INSIDE:
141
+ return None
142
+ parts = relative[1:]
143
+ if parts[-1] == INIT:
144
+ parts = parts[:-1]
145
+ return Place(
146
+ package=relative[0],
147
+ parts=parts,
148
+ directories=relative[1:-1],
149
+ )
150
+
151
+
152
+ def _relative(
153
+ *,
154
+ path: Path,
155
+ source: Path,
156
+ ) -> tuple[str, ...] | None:
157
+ try:
158
+ inside = path.resolve().relative_to(source.resolve())
159
+ except ValueError:
160
+ return None
161
+ return inside.with_suffix("").parts