python-checks 0.4.2__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 (167) hide show
  1. {python_checks-0.4.2 → python_checks-0.6.0}/PKG-INFO +9 -4
  2. {python_checks-0.4.2 → python_checks-0.6.0}/README.md +6 -3
  3. {python_checks-0.4.2 → python_checks-0.6.0}/pyproject.toml +6 -2
  4. {python_checks-0.4.2 → python_checks-0.6.0}/pyproject.toml.orig +10 -2
  5. python_checks-0.6.0/src/py_checks/checks/__init__.py +21 -0
  6. {python_checks-0.4.2 → 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.6.0/src/py_checks/checks/api/_edge_declarations.py +388 -0
  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.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/checks/database/__init__.py +7 -5
  17. {python_checks-0.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/checks/database/_model_boundary.py +37 -36
  21. {python_checks-0.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/checks/database/_schema_drift.py +50 -47
  24. {python_checks-0.4.2 → 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.4.2 → 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.4.2 → 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.4.2 → 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.4.2 → 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.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/checks/placement/_operation_shape.py +56 -54
  45. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/checks/placement/_required_class.py +28 -28
  46. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/checks/signatures/__init__.py +6 -5
  47. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/checks/signatures/_function_length.py +18 -17
  48. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/checks/signatures/_functions.py +13 -12
  49. {python_checks-0.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/checks/signatures/_module_length.py +8 -8
  52. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/checks/signatures/_nesting.py +20 -20
  53. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/checks/signatures/_signature_layout.py +46 -47
  54. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/checks/types/__init__.py +5 -4
  55. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/checks/types/_annotation_shapes.py +20 -20
  56. {python_checks-0.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/checks/types/_constant_annotations.py +18 -17
  59. {python_checks-0.4.2 → 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.4.2 → 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.4.2 → 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.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/cli/commands/_summary.py +3 -3
  71. {python_checks-0.4.2 → 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.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/contracts/_layout.py +7 -6
  82. {python_checks-0.4.2 → 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.4.2 → 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.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/core/_errors.py +4 -4
  89. {python_checks-0.4.2 → 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.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/core/_registry.py +15 -13
  95. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/core/_report.py +8 -7
  96. {python_checks-0.4.2 → 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.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/environment/_constants.py +1 -1
  102. {python_checks-0.4.2 → 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.4.2 → python_checks-0.6.0}/src/py_checks/sync/_sync.py +11 -10
  115. python_checks-0.4.2/src/py_checks/checks/__init__.py +0 -20
  116. python_checks-0.4.2/src/py_checks/checks/_layout.py +0 -239
  117. python_checks-0.4.2/src/py_checks/checks/_location.py +0 -139
  118. python_checks-0.4.2/src/py_checks/checks/_names.py +0 -86
  119. python_checks-0.4.2/src/py_checks/checks/api/__init__.py +0 -13
  120. python_checks-0.4.2/src/py_checks/checks/api/_endpoint_declarations.py +0 -204
  121. python_checks-0.4.2/src/py_checks/checks/api/_marker.py +0 -5
  122. python_checks-0.4.2/src/py_checks/checks/calls/__init__.py +0 -13
  123. python_checks-0.4.2/src/py_checks/checks/calls/_marker.py +0 -5
  124. python_checks-0.4.2/src/py_checks/checks/database/_confined_calls.py +0 -118
  125. python_checks-0.4.2/src/py_checks/checks/database/_marker.py +0 -5
  126. python_checks-0.4.2/src/py_checks/checks/database/_raw_sql.py +0 -108
  127. python_checks-0.4.2/src/py_checks/checks/effects/__init__.py +0 -19
  128. python_checks-0.4.2/src/py_checks/checks/effects/_determinism.py +0 -105
  129. python_checks-0.4.2/src/py_checks/checks/effects/_marker.py +0 -5
  130. python_checks-0.4.2/src/py_checks/checks/hygiene/__init__.py +0 -14
  131. python_checks-0.4.2/src/py_checks/checks/hygiene/_marker.py +0 -5
  132. python_checks-0.4.2/src/py_checks/checks/imports/__init__.py +0 -25
  133. python_checks-0.4.2/src/py_checks/checks/imports/_marker.py +0 -7
  134. python_checks-0.4.2/src/py_checks/checks/imports/_sealed.py +0 -100
  135. python_checks-0.4.2/src/py_checks/checks/placement/__init__.py +0 -35
  136. python_checks-0.4.2/src/py_checks/checks/placement/_class_placement.py +0 -79
  137. python_checks-0.4.2/src/py_checks/checks/placement/_marker.py +0 -7
  138. python_checks-0.4.2/src/py_checks/checks/signatures/_marker.py +0 -7
  139. python_checks-0.4.2/src/py_checks/checks/types/_confined_types.py +0 -129
  140. python_checks-0.4.2/src/py_checks/checks/types/_marker.py +0 -5
  141. python_checks-0.4.2/src/py_checks/cli/__init__.py +0 -10
  142. python_checks-0.4.2/src/py_checks/cli/_protocols.py +0 -19
  143. python_checks-0.4.2/src/py_checks/cli/commands/_doctor.py +0 -293
  144. python_checks-0.4.2/src/py_checks/cli/commands/_explain.py +0 -64
  145. python_checks-0.4.2/src/py_checks/cli/commands/_run.py +0 -167
  146. python_checks-0.4.2/src/py_checks/config/__init__.py +0 -32
  147. python_checks-0.4.2/src/py_checks/config/_base.py +0 -34
  148. python_checks-0.4.2/src/py_checks/config/_config.py +0 -110
  149. python_checks-0.4.2/src/py_checks/config/_constants.py +0 -31
  150. python_checks-0.4.2/src/py_checks/config/_errors.py +0 -12
  151. python_checks-0.4.2/src/py_checks/config/_toml.py +0 -24
  152. python_checks-0.4.2/src/py_checks/contracts/__init__.py +0 -26
  153. python_checks-0.4.2/src/py_checks/contracts/_constants.py +0 -18
  154. python_checks-0.4.2/src/py_checks/contracts/_settings.py +0 -41
  155. python_checks-0.4.2/src/py_checks/core/_constants.py +0 -15
  156. python_checks-0.4.2/src/py_checks/core/_edit.py +0 -92
  157. python_checks-0.4.2/src/py_checks/core/_format.py +0 -30
  158. python_checks-0.4.2/src/py_checks/core/_paths.py +0 -49
  159. python_checks-0.4.2/src/py_checks/core/_protocols.py +0 -99
  160. python_checks-0.4.2/src/py_checks/core/_settings.py +0 -44
  161. python_checks-0.4.2/src/py_checks/core/_violation.py +0 -73
  162. python_checks-0.4.2/src/py_checks/environment/__init__.py +0 -14
  163. python_checks-0.4.2/src/py_checks/environment/_settings.py +0 -40
  164. python_checks-0.4.2/src/py_checks/sync/__init__.py +0 -16
  165. {python_checks-0.4.2 → python_checks-0.6.0}/LICENSE +0 -0
  166. {python_checks-0.4.2 → python_checks-0.6.0}/src/py_checks/__init__.py +0 -0
  167. {python_checks-0.4.2 → 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.4.2
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">
@@ -59,7 +61,7 @@ src/app/modules/cashout/application/offer.py:34:9: determinism: uuid4() is not d
59
61
  the identifier is handed out at the edge and passed inwards
60
62
  src/app/infra/database/models/bet.py:51:5: model-columns: stake is a Numeric with no bound;
61
63
  money is described by Numeric(18, 4)
62
- src/app/presentation/api/v1/routers/bets.py:22:1: endpoint-declarations: POST /bets
64
+ src/app/presentation/api/v1/routers/bets.py:22:1: edge-declarations: POST /bets
63
65
  did not name a response_model
64
66
  ```
65
67
 
@@ -139,7 +141,8 @@ Twenty-eight rules in nine groups:
139
141
  | `types` | bounds on fields, the shape of an annotation, immutability |
140
142
  | `database` | the model's boundary, a column's material, the shape of a query, the schema |
141
143
  | `effects` | the clock, the dice, and the name of an event in the log |
142
- | `api` | what a route answers with and what it must declare |
144
+ | `api` | what an entrance declares about itself |
145
+ | `errors` | the code a refusal carries |
143
146
  | `calls` | a function whose call sites can be listed |
144
147
  | `hygiene` | a ceiling on a dependency |
145
148
 
@@ -173,7 +176,8 @@ Twenty-eight rules in nine groups:
173
176
  | `schema-drift` | the models and the migrations describe different schemas | environment |
174
177
  | `determinism` | the code reads the clock, the dice or a new identifier itself | file |
175
178
  | `log-events` | an event in the log is named by something other than an enum member | file |
176
- | `endpoint-declarations` | a route did not say what it answers with | file |
179
+ | `edge-declarations` | an entrance did not say how it behaves | file |
180
+ | `refusals` | a no nobody can branch on | file |
177
181
  | `confined-functions` | a named function was called from somewhere it may not be | file |
178
182
  | `dependency-bounds` | a dependency may move to a version nobody has ever run | project |
179
183
 
@@ -349,6 +353,7 @@ obeys `ignore`, and is lifted by a mark.
349
353
  | `py-checks explain <code>` | what a rule asks for and what it can be told |
350
354
  | `py-checks sync [--check]` | build the import contracts and `.env.example` |
351
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]` |
352
357
 
353
358
  ## Development
354
359
 
@@ -38,7 +38,7 @@ src/app/modules/cashout/application/offer.py:34:9: determinism: uuid4() is not d
38
38
  the identifier is handed out at the edge and passed inwards
39
39
  src/app/infra/database/models/bet.py:51:5: model-columns: stake is a Numeric with no bound;
40
40
  money is described by Numeric(18, 4)
41
- src/app/presentation/api/v1/routers/bets.py:22:1: endpoint-declarations: POST /bets
41
+ src/app/presentation/api/v1/routers/bets.py:22:1: edge-declarations: POST /bets
42
42
  did not name a response_model
43
43
  ```
44
44
 
@@ -118,7 +118,8 @@ Twenty-eight rules in nine groups:
118
118
  | `types` | bounds on fields, the shape of an annotation, immutability |
119
119
  | `database` | the model's boundary, a column's material, the shape of a query, the schema |
120
120
  | `effects` | the clock, the dice, and the name of an event in the log |
121
- | `api` | what a route answers with and what it must declare |
121
+ | `api` | what an entrance declares about itself |
122
+ | `errors` | the code a refusal carries |
122
123
  | `calls` | a function whose call sites can be listed |
123
124
  | `hygiene` | a ceiling on a dependency |
124
125
 
@@ -152,7 +153,8 @@ Twenty-eight rules in nine groups:
152
153
  | `schema-drift` | the models and the migrations describe different schemas | environment |
153
154
  | `determinism` | the code reads the clock, the dice or a new identifier itself | file |
154
155
  | `log-events` | an event in the log is named by something other than an enum member | file |
155
- | `endpoint-declarations` | a route did not say what it answers with | file |
156
+ | `edge-declarations` | an entrance did not say how it behaves | file |
157
+ | `refusals` | a no nobody can branch on | file |
156
158
  | `confined-functions` | a named function was called from somewhere it may not be | file |
157
159
  | `dependency-bounds` | a dependency may move to a version nobody has ever run | project |
158
160
 
@@ -328,6 +330,7 @@ obeys `ignore`, and is lifted by a mark.
328
330
  | `py-checks explain <code>` | what a rule asks for and what it can be told |
329
331
  | `py-checks sync [--check]` | build the import contracts and `.env.example` |
330
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]` |
331
334
 
332
335
  ## Development
333
336
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.4.2"
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
 
@@ -41,7 +44,7 @@ confined-types = "py_checks.checks.types:ConfinedTypes"
41
44
  constant-annotations = "py_checks.checks.types:ConstantAnnotations"
42
45
  dependency-bounds = "py_checks.checks.hygiene:DependencyBounds"
43
46
  determinism = "py_checks.checks.effects:Determinism"
44
- endpoint-declarations = "py_checks.checks.api:EndpointDeclarations"
47
+ edge-declarations = "py_checks.checks.api:EdgeDeclarations"
45
48
  frozen-dataclasses = "py_checks.checks.types:FrozenDataclasses"
46
49
  function-length = "py_checks.checks.signatures:FunctionLength"
47
50
  keyword-only-arguments = "py_checks.checks.signatures:KeywordOnlyArguments"
@@ -52,6 +55,7 @@ module-length = "py_checks.checks.signatures:ModuleLength"
52
55
  nesting = "py_checks.checks.signatures:Nesting"
53
56
  operation-shape = "py_checks.checks.placement:OperationShape"
54
57
  raw-sql = "py_checks.checks.database:RawSql"
58
+ refusals = "py_checks.checks.errors:Refusals"
55
59
  required-class = "py_checks.checks.placement:RequiredClass"
56
60
  schema-drift = "py_checks.checks.database:SchemaDrift"
57
61
  sealed-imports = "py_checks.checks.imports:SealedImports"
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.4.2"
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
 
@@ -44,7 +51,7 @@ confined-types = "py_checks.checks.types:ConfinedTypes"
44
51
  constant-annotations = "py_checks.checks.types:ConstantAnnotations"
45
52
  dependency-bounds = "py_checks.checks.hygiene:DependencyBounds"
46
53
  determinism = "py_checks.checks.effects:Determinism"
47
- endpoint-declarations = "py_checks.checks.api:EndpointDeclarations"
54
+ edge-declarations = "py_checks.checks.api:EdgeDeclarations"
48
55
  frozen-dataclasses = "py_checks.checks.types:FrozenDataclasses"
49
56
  function-length = "py_checks.checks.signatures:FunctionLength"
50
57
  keyword-only-arguments = "py_checks.checks.signatures:KeywordOnlyArguments"
@@ -55,6 +62,7 @@ module-length = "py_checks.checks.signatures:ModuleLength"
55
62
  nesting = "py_checks.checks.signatures:Nesting"
56
63
  operation-shape = "py_checks.checks.placement:OperationShape"
57
64
  raw-sql = "py_checks.checks.database:RawSql"
65
+ refusals = "py_checks.checks.errors:Refusals"
58
66
  required-class = "py_checks.checks.placement:RequiredClass"
59
67
  schema-drift = "py_checks.checks.database:SchemaDrift"
60
68
  sealed-imports = "py_checks.checks.imports:SealedImports"
@@ -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