python-checks 0.4.2__tar.gz → 0.5.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 (109) hide show
  1. {python_checks-0.4.2 → python_checks-0.5.0}/PKG-INFO +6 -4
  2. {python_checks-0.4.2 → python_checks-0.5.0}/README.md +5 -3
  3. {python_checks-0.4.2 → python_checks-0.5.0}/pyproject.toml +3 -2
  4. {python_checks-0.4.2 → python_checks-0.5.0}/pyproject.toml.orig +3 -2
  5. python_checks-0.5.0/src/py_checks/checks/api/__init__.py +18 -0
  6. python_checks-0.5.0/src/py_checks/checks/api/_edge_declarations.py +381 -0
  7. python_checks-0.5.0/src/py_checks/checks/errors/__init__.py +10 -0
  8. python_checks-0.5.0/src/py_checks/checks/errors/_marker.py +5 -0
  9. python_checks-0.5.0/src/py_checks/checks/errors/_refusals.py +159 -0
  10. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/config/_config.py +49 -15
  11. python_checks-0.4.2/src/py_checks/checks/api/__init__.py +0 -13
  12. python_checks-0.4.2/src/py_checks/checks/api/_endpoint_declarations.py +0 -204
  13. {python_checks-0.4.2 → python_checks-0.5.0}/LICENSE +0 -0
  14. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/__init__.py +0 -0
  15. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/__init__.py +0 -0
  16. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/_kind.py +0 -0
  17. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/_layout.py +0 -0
  18. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/_location.py +0 -0
  19. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/_names.py +0 -0
  20. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/api/_marker.py +0 -0
  21. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/calls/__init__.py +0 -0
  22. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/calls/_confined_functions.py +0 -0
  23. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/calls/_marker.py +0 -0
  24. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/__init__.py +0 -0
  25. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/_bound_checks.py +0 -0
  26. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/_confined_calls.py +0 -0
  27. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/_marker.py +0 -0
  28. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/_model_boundary.py +0 -0
  29. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/_model_columns.py +0 -0
  30. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/_raw_sql.py +0 -0
  31. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/_schema_drift.py +0 -0
  32. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/database/_statement_keys.py +0 -0
  33. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/effects/__init__.py +0 -0
  34. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/effects/_determinism.py +0 -0
  35. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/effects/_log_events.py +0 -0
  36. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/effects/_marker.py +0 -0
  37. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/hygiene/__init__.py +0 -0
  38. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/hygiene/_dependency_bounds.py +0 -0
  39. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/hygiene/_marker.py +0 -0
  40. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/imports/__init__.py +0 -0
  41. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/imports/_confined.py +0 -0
  42. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/imports/_marker.py +0 -0
  43. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/imports/_sealed.py +0 -0
  44. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/imports/_statements.py +0 -0
  45. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/placement/__init__.py +0 -0
  46. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/placement/_class_modules.py +0 -0
  47. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/placement/_class_placement.py +0 -0
  48. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/placement/_marker.py +0 -0
  49. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/placement/_operation_shape.py +0 -0
  50. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/placement/_required_class.py +0 -0
  51. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/signatures/__init__.py +0 -0
  52. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/signatures/_function_length.py +0 -0
  53. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/signatures/_functions.py +0 -0
  54. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/signatures/_keyword_only.py +0 -0
  55. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/signatures/_marker.py +0 -0
  56. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/signatures/_module_length.py +0 -0
  57. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/signatures/_nesting.py +0 -0
  58. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/signatures/_signature_layout.py +0 -0
  59. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/types/__init__.py +0 -0
  60. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/types/_annotation_shapes.py +0 -0
  61. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/types/_config_fields.py +0 -0
  62. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/types/_confined_types.py +0 -0
  63. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/types/_constant_annotations.py +0 -0
  64. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/types/_frozen_dataclasses.py +0 -0
  65. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/checks/types/_marker.py +0 -0
  66. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/__init__.py +0 -0
  67. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/_app.py +0 -0
  68. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/_protocols.py +0 -0
  69. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/commands/__init__.py +0 -0
  70. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/commands/_doctor.py +0 -0
  71. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/commands/_explain.py +0 -0
  72. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/commands/_list.py +0 -0
  73. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/commands/_run.py +0 -0
  74. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/commands/_summary.py +0 -0
  75. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/cli/commands/_sync.py +0 -0
  76. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/config/__init__.py +0 -0
  77. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/config/_base.py +0 -0
  78. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/config/_constants.py +0 -0
  79. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/config/_errors.py +0 -0
  80. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/config/_loader.py +0 -0
  81. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/config/_toml.py +0 -0
  82. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/contracts/__init__.py +0 -0
  83. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/contracts/_constants.py +0 -0
  84. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/contracts/_layout.py +0 -0
  85. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/contracts/_render.py +0 -0
  86. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/contracts/_settings.py +0 -0
  87. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/__init__.py +0 -0
  88. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_constants.py +0 -0
  89. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_discovery.py +0 -0
  90. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_edit.py +0 -0
  91. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_errors.py +0 -0
  92. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_fixer.py +0 -0
  93. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_format.py +0 -0
  94. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_markers.py +0 -0
  95. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_paths.py +0 -0
  96. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_protocols.py +0 -0
  97. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_registry.py +0 -0
  98. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_report.py +0 -0
  99. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_runner.py +0 -0
  100. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_settings.py +0 -0
  101. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_source.py +0 -0
  102. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/core/_violation.py +0 -0
  103. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/environment/__init__.py +0 -0
  104. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/environment/_constants.py +0 -0
  105. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/environment/_render.py +0 -0
  106. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/environment/_settings.py +0 -0
  107. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/py.typed +0 -0
  108. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/sync/__init__.py +0 -0
  109. {python_checks-0.4.2 → python_checks-0.5.0}/src/py_checks/sync/_sync.py +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.5.0
4
4
  Summary: Проверки архитектурных соглашений проекта
5
5
  Author: Armontex
6
6
  Author-email: Armontex <windle1337@gmail.com>
@@ -59,7 +59,7 @@ src/app/modules/cashout/application/offer.py:34:9: determinism: uuid4() is not d
59
59
  the identifier is handed out at the edge and passed inwards
60
60
  src/app/infra/database/models/bet.py:51:5: model-columns: stake is a Numeric with no bound;
61
61
  money is described by Numeric(18, 4)
62
- src/app/presentation/api/v1/routers/bets.py:22:1: endpoint-declarations: POST /bets
62
+ src/app/presentation/api/v1/routers/bets.py:22:1: edge-declarations: POST /bets
63
63
  did not name a response_model
64
64
  ```
65
65
 
@@ -139,7 +139,8 @@ Twenty-eight rules in nine groups:
139
139
  | `types` | bounds on fields, the shape of an annotation, immutability |
140
140
  | `database` | the model's boundary, a column's material, the shape of a query, the schema |
141
141
  | `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 |
142
+ | `api` | what an entrance declares about itself |
143
+ | `errors` | the code a refusal carries |
143
144
  | `calls` | a function whose call sites can be listed |
144
145
  | `hygiene` | a ceiling on a dependency |
145
146
 
@@ -173,7 +174,8 @@ Twenty-eight rules in nine groups:
173
174
  | `schema-drift` | the models and the migrations describe different schemas | environment |
174
175
  | `determinism` | the code reads the clock, the dice or a new identifier itself | file |
175
176
  | `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 |
177
+ | `edge-declarations` | an entrance did not say how it behaves | file |
178
+ | `refusals` | a no nobody can branch on | file |
177
179
  | `confined-functions` | a named function was called from somewhere it may not be | file |
178
180
  | `dependency-bounds` | a dependency may move to a version nobody has ever run | project |
179
181
 
@@ -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
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "python-checks"
3
- version = "0.4.2"
3
+ version = "0.5.0"
4
4
  description = "Проверки архитектурных соглашений проекта"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -41,7 +41,7 @@ confined-types = "py_checks.checks.types:ConfinedTypes"
41
41
  constant-annotations = "py_checks.checks.types:ConstantAnnotations"
42
42
  dependency-bounds = "py_checks.checks.hygiene:DependencyBounds"
43
43
  determinism = "py_checks.checks.effects:Determinism"
44
- endpoint-declarations = "py_checks.checks.api:EndpointDeclarations"
44
+ edge-declarations = "py_checks.checks.api:EdgeDeclarations"
45
45
  frozen-dataclasses = "py_checks.checks.types:FrozenDataclasses"
46
46
  function-length = "py_checks.checks.signatures:FunctionLength"
47
47
  keyword-only-arguments = "py_checks.checks.signatures:KeywordOnlyArguments"
@@ -52,6 +52,7 @@ module-length = "py_checks.checks.signatures:ModuleLength"
52
52
  nesting = "py_checks.checks.signatures:Nesting"
53
53
  operation-shape = "py_checks.checks.placement:OperationShape"
54
54
  raw-sql = "py_checks.checks.database:RawSql"
55
+ refusals = "py_checks.checks.errors:Refusals"
55
56
  required-class = "py_checks.checks.placement:RequiredClass"
56
57
  schema-drift = "py_checks.checks.database:SchemaDrift"
57
58
  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.5.0"
4
4
  description = "Проверки архитектурных соглашений проекта"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -44,7 +44,7 @@ confined-types = "py_checks.checks.types:ConfinedTypes"
44
44
  constant-annotations = "py_checks.checks.types:ConstantAnnotations"
45
45
  dependency-bounds = "py_checks.checks.hygiene:DependencyBounds"
46
46
  determinism = "py_checks.checks.effects:Determinism"
47
- endpoint-declarations = "py_checks.checks.api:EndpointDeclarations"
47
+ edge-declarations = "py_checks.checks.api:EdgeDeclarations"
48
48
  frozen-dataclasses = "py_checks.checks.types:FrozenDataclasses"
49
49
  function-length = "py_checks.checks.signatures:FunctionLength"
50
50
  keyword-only-arguments = "py_checks.checks.signatures:KeywordOnlyArguments"
@@ -55,6 +55,7 @@ module-length = "py_checks.checks.signatures:ModuleLength"
55
55
  nesting = "py_checks.checks.signatures:Nesting"
56
56
  operation-shape = "py_checks.checks.placement:OperationShape"
57
57
  raw-sql = "py_checks.checks.database:RawSql"
58
+ refusals = "py_checks.checks.errors:Refusals"
58
59
  required-class = "py_checks.checks.placement:RequiredClass"
59
60
  schema-drift = "py_checks.checks.database:SchemaDrift"
60
61
  sealed-imports = "py_checks.checks.imports:SealedImports"
@@ -0,0 +1,18 @@
1
+ """API и события.
2
+
3
+ Вход в процесс объявляет в декораторе всё, что за него решили: механизм у
4
+ фреймворка есть, требования писать — нет, а каждое его умолчание — решение,
5
+ принятое не этим проектом.
6
+ """
7
+
8
+ from py_checks.checks.api._edge_declarations import (
9
+ KNOWN,
10
+ Edge,
11
+ EdgeDeclarations,
12
+ Edges,
13
+ Framework,
14
+ Shape,
15
+ )
16
+ from py_checks.checks.api._marker import MARKER
17
+
18
+ __all__ = ["KNOWN", "MARKER", "Edge", "EdgeDeclarations", "Edges", "Framework", "Shape"]
@@ -0,0 +1,381 @@
1
+ """Вход в процесс объявляет в декораторе всё, что за него решили."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ast
6
+ from dataclasses import dataclass
7
+ from enum import StrEnum
8
+ from http import HTTPStatus
9
+ from typing import TYPE_CHECKING, ClassVar, Final, Self
10
+
11
+ from pydantic import model_validator
12
+
13
+ from py_checks.checks.api._marker import MARKER
14
+ from py_checks.config import OPEN, CheckSettings
15
+ from py_checks.core import Scope, Violation, settings_as
16
+
17
+ if TYPE_CHECKING:
18
+ from collections.abc import Iterator
19
+
20
+ from py_checks.core import ParsedFile
21
+
22
+ CODE: Final = "edge-declarations"
23
+
24
+ STATUS: Final = "status_code"
25
+
26
+
27
+ class Framework(StrEnum):
28
+ """Фреймворк, которым написан вход."""
29
+
30
+ FASTAPI = "fastapi"
31
+ FASTSTREAM = "faststream"
32
+
33
+
34
+ @dataclass(frozen=True, slots=True)
35
+ class Shape:
36
+ """Как фреймворк записывает вход. Это знание библиотеки, а не проекта.
37
+
38
+ Проект решает, что вход обязан объявить; что такое «вход» у FastAPI и у
39
+ FastStream — решено их авторами, и таблица, которую проект писал бы об
40
+ этом, была бы пересказом чужой документации, стареющим вместе с ней.
41
+ """
42
+
43
+ # Имена методов, которыми вход объявляют: `broker.subscriber`, `router.post`.
44
+ # Имя объекта слева не читается — это имя переменной, а правило про то, как
45
+ # называют переменную, было бы правилом про орфографию.
46
+ methods: tuple[str, ...]
47
+
48
+ # Только декоратором. У маршрута это обязательно: его `methods` — `get`,
49
+ # `post`, `delete`, то есть имена, которыми зовут и клиента HTTP, и правило,
50
+ # читающее любой `.post(...)`, нашло бы маршрут в первом же адаптере к
51
+ # соседнему сервису. Подписку так не спутать ни с чем, а пишут её и
52
+ # декоратором, и вызовом: её держат в переменной и применяют к обработчику
53
+ # отдельно, потому что до старта у неё берут клиента.
54
+ decorated: bool
55
+
56
+ # Слово, которым сообщение зовёт первый аргумент.
57
+ subject: str
58
+
59
+ # Имя первого аргумента, если он пишется словом; `None` — он позиционный.
60
+ named: str | None
61
+
62
+ # Аргумент, объявляющий тело ответа, и статусы, у которых тела не бывает.
63
+ body: str | None = None
64
+ bodiless: tuple[int, ...] = ()
65
+
66
+ # Флаг, которым вход говорит, что в схеме его нет.
67
+ exempt: str | None = None
68
+
69
+
70
+ KNOWN: Final[dict[str, Shape]] = {
71
+ Framework.FASTAPI: Shape(
72
+ methods=("get", "post", "put", "patch", "delete", "head", "options", "trace"),
73
+ decorated=True,
74
+ subject="путь",
75
+ named="path",
76
+ body="response_model",
77
+ bodiless=(
78
+ int(HTTPStatus.NO_CONTENT),
79
+ int(HTTPStatus.RESET_CONTENT),
80
+ int(HTTPStatus.NOT_MODIFIED),
81
+ ),
82
+ exempt="include_in_schema",
83
+ ),
84
+ Framework.FASTSTREAM: Shape(
85
+ methods=("subscriber",),
86
+ decorated=False,
87
+ subject="топик",
88
+ named=None,
89
+ ),
90
+ }
91
+
92
+
93
+ class Edge(CheckSettings):
94
+ """Что вход этого фреймворка обязан назвать.
95
+
96
+ Каждое имя здесь — решение, у которого в библиотеке фреймворка есть
97
+ умолчание, и умолчание это принято не тем, кто пишет сервис.
98
+ """
99
+
100
+ required: tuple[str, ...] = ()
101
+
102
+
103
+ class Edges(CheckSettings):
104
+ """Таблица входов: блок на фреймворк.
105
+
106
+ ```toml
107
+ [edge-declarations.fastapi]
108
+ required = ["path", "status_code", "summary", "responses"]
109
+
110
+ [edge-declarations.faststream]
111
+ required = ["group_id", "parser", "decoder", "ack_policy"]
112
+ ```
113
+ """
114
+
115
+ model_config = OPEN
116
+ __pydantic_extra__: dict[str, Edge] # type: ignore[assignment]
117
+
118
+ @model_validator(mode="after")
119
+ def _known(self) -> Self:
120
+ """Имя блока — фреймворк, о котором библиотека что-то знает."""
121
+ unknown = sorted(set(self.frameworks) - set(KNOWN))
122
+ if unknown:
123
+ listed = ", ".join(repr(name) for name in unknown)
124
+ known = ", ".join(sorted(KNOWN))
125
+ message = f"{listed}: про такой фреймворк правило не знает; известны {known}"
126
+ raise ValueError(message)
127
+ return self
128
+
129
+ @property
130
+ def frameworks(self) -> dict[str, Edge]:
131
+ return self.__pydantic_extra__
132
+
133
+
134
+ class EdgeDeclarations:
135
+ """Падает, если вход в процесс не сказал, как он себя ведёт.
136
+
137
+ Декоратор входа — это контракт. У маршрута его читает тот, кто читает
138
+ сгенерированную схему: соседний сервис, человек, пишущий клиент, — и поле,
139
+ которого в декораторе нет, для него не существует, что бы ни возвращало
140
+ тело функции. У подписки его читает тот, кто разбирается, почему запись
141
+ обработана дважды или не обработана вовсе.
142
+
143
+ Механизм у фреймворка есть, требования писать — нет, и каждое умолчание
144
+ там — решение, принятое не этим проектом. Маршрут без `summary` попадёт в
145
+ схему с именем функции вместо описания, а с пустым `responses` — с
146
+ обещанием, что отказов у него не бывает. Подписка без `ack_policy` вернёт
147
+ брокеру запись, которую он только что доставил, а без `auto_offset_reset`
148
+ пропустит то отставание, ради которого новая группа и заводится.
149
+
150
+ Что такое вход у FastAPI и у FastStream — знает библиотека: имена методов,
151
+ декоратор это или вызов, как пишется первый аргумент. Проект называет одно:
152
+ что вход обязан объявить.
153
+
154
+ Тело объявляется отдельно от прочего и не требуется там, где его не
155
+ бывает: 204, 205 и 304 — это статусы без тела, и модель ответа рядом с
156
+ ними обещает то, что протокол запрещает. Статус, записанный не числом и не
157
+ членом `HTTPStatus`, читается как неизвестный, а неизвестный считается
158
+ имеющим тело: проверка, сработавшая зря, снимается пометкой, а
159
+ промолчавшая — это контракт, которого никто не хватится.
160
+
161
+ Вход, выведенный из схемы (`include_in_schema=False`), правило не трогает:
162
+ схема — это то, что оно защищает, а такого маршрута в ней нет.
163
+
164
+ Настройки: блок на фреймворк, в нём `required`.
165
+ """
166
+
167
+ code: ClassVar[str] = CODE
168
+ Settings: ClassVar[type[CheckSettings]] = Edges
169
+ scope: ClassVar[Scope] = Scope.FILE
170
+ marker: ClassVar[str] = MARKER
171
+
172
+ @classmethod
173
+ def run(
174
+ cls,
175
+ *,
176
+ file: ParsedFile,
177
+ settings: CheckSettings,
178
+ ) -> Iterator[Violation]:
179
+ frameworks = settings_as(
180
+ settings=settings,
181
+ model=Edges,
182
+ code=CODE,
183
+ ).frameworks
184
+ decorators = cls._decorators(tree=file.tree)
185
+ for node in ast.walk(file.tree):
186
+ if not isinstance(node, ast.Call):
187
+ continue
188
+ found = cls._matched(
189
+ call=node,
190
+ frameworks=frameworks,
191
+ )
192
+ if found is None:
193
+ continue
194
+ shape, edge = found
195
+ if shape.decorated and node not in decorators:
196
+ continue
197
+ yield from cls._judged(
198
+ call=node,
199
+ file=file,
200
+ shape=shape,
201
+ edge=edge,
202
+ )
203
+
204
+ @staticmethod
205
+ def _decorators(*, tree: ast.Module) -> set[ast.Call]:
206
+ """Вызовы, стоящие декоратором: остальное для такого входа — не он."""
207
+ return {
208
+ decorator
209
+ for node in ast.walk(tree)
210
+ if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)
211
+ for decorator in node.decorator_list
212
+ if isinstance(decorator, ast.Call)
213
+ }
214
+
215
+ @staticmethod
216
+ def _matched(
217
+ *,
218
+ call: ast.Call,
219
+ frameworks: dict[str, Edge],
220
+ ) -> tuple[Shape, Edge] | None:
221
+ """Вход какого фреймворка тут объявлен; `None` — не вход."""
222
+ if not isinstance(call.func, ast.Attribute):
223
+ return None
224
+ for name, edge in frameworks.items():
225
+ shape = KNOWN[name]
226
+ if call.func.attr in shape.methods:
227
+ return shape, edge
228
+ return None
229
+
230
+ @classmethod
231
+ def _judged(
232
+ cls,
233
+ *,
234
+ call: ast.Call,
235
+ file: ParsedFile,
236
+ shape: Shape,
237
+ edge: Edge,
238
+ ) -> Iterator[Violation]:
239
+ if cls._unpublished(
240
+ call=call,
241
+ exempt=shape.exempt,
242
+ ):
243
+ return
244
+ named = cls._name(
245
+ call=call,
246
+ shape=shape,
247
+ )
248
+ declared = {keyword.arg for keyword in call.keywords}
249
+ yield from cls._first(
250
+ call=call,
251
+ file=file,
252
+ shape=shape,
253
+ named=named,
254
+ )
255
+ for wanted in edge.required:
256
+ # Написанный позиционно там, где так не пишут, уже назван выше;
257
+ # второе замечание о том же входе читается как второй промах.
258
+ if wanted in declared or (wanted == shape.named and call.args):
259
+ continue
260
+ yield cls._violation(
261
+ call=call,
262
+ file=file,
263
+ message=f"{named} не объявляет {wanted}=",
264
+ )
265
+ yield from cls._bodied(
266
+ call=call,
267
+ file=file,
268
+ shape=shape,
269
+ declared=declared,
270
+ named=named,
271
+ )
272
+
273
+ @classmethod
274
+ def _first(
275
+ cls,
276
+ *,
277
+ call: ast.Call,
278
+ file: ParsedFile,
279
+ shape: Shape,
280
+ named: str,
281
+ ) -> Iterator[Violation]:
282
+ """Первый аргумент: написан не так, как его пишут, или не написан."""
283
+ if shape.named is not None:
284
+ if call.args:
285
+ yield cls._violation(
286
+ call=call,
287
+ file=file,
288
+ message=f"{named} передаёт {shape.subject} позиционно; напиши {shape.named}=",
289
+ )
290
+ return
291
+ if not call.args:
292
+ yield cls._violation(
293
+ call=call,
294
+ file=file,
295
+ message=f"{named} не называет {shape.subject}; он пишется первым аргументом",
296
+ )
297
+
298
+ @classmethod
299
+ def _bodied(
300
+ cls,
301
+ *,
302
+ call: ast.Call,
303
+ file: ParsedFile,
304
+ shape: Shape,
305
+ declared: set[str | None],
306
+ named: str,
307
+ ) -> Iterator[Violation]:
308
+ if shape.body is None or shape.body in declared:
309
+ return
310
+ if cls._status(call=call) in shape.bodiless:
311
+ return
312
+ yield cls._violation(
313
+ call=call,
314
+ file=file,
315
+ message=(
316
+ f"{named} не объявляет {shape.body}= и отвечает телом; "
317
+ f"без него отвечают {', '.join(str(status) for status in shape.bodiless)}"
318
+ ),
319
+ )
320
+
321
+ @staticmethod
322
+ def _violation(
323
+ *,
324
+ call: ast.Call,
325
+ file: ParsedFile,
326
+ message: str,
327
+ ) -> Violation:
328
+ return Violation.from_node(
329
+ node=call,
330
+ path=file.path,
331
+ code=CODE,
332
+ message=message,
333
+ )
334
+
335
+ @staticmethod
336
+ def _unpublished(
337
+ *,
338
+ call: ast.Call,
339
+ exempt: str | None,
340
+ ) -> bool:
341
+ """Вход сказал, что в схеме его нет."""
342
+ return exempt is not None and any(
343
+ keyword.arg == exempt
344
+ and isinstance(keyword.value, ast.Constant)
345
+ and keyword.value.value is False
346
+ for keyword in call.keywords
347
+ )
348
+
349
+ @staticmethod
350
+ def _name(
351
+ *,
352
+ call: ast.Call,
353
+ shape: Shape,
354
+ ) -> str:
355
+ """`POST '/tickets'`, `SUBSCRIBER 'bets.placed'` — как бы ни был записан.
356
+
357
+ Предмет объявления читается и из позиции, и из слова: сообщение обязано
358
+ назвать вход и в том файле, где слова как раз нет, — «GET не объявляет
359
+ summary» в модуле с шестью GET не называет ничего.
360
+ """
361
+ attribute = call.func
362
+ method = attribute.attr.upper() if isinstance(attribute, ast.Attribute) else ""
363
+ written = [keyword.value for keyword in call.keywords if keyword.arg == shape.named]
364
+ subject = call.args[:1] + written
365
+ return f"{method} {ast.unparse(subject[0])}" if subject else method
366
+
367
+ @staticmethod
368
+ def _status(*, call: ast.Call) -> int | None:
369
+ """Статус, если он записан так, что его видно по файлу."""
370
+ for keyword in call.keywords:
371
+ if keyword.arg != STATUS:
372
+ continue
373
+ match keyword.value:
374
+ case ast.Constant(value=int() as status):
375
+ return status
376
+ case ast.Attribute(value=ast.Name(id="HTTPStatus"), attr=name):
377
+ found = getattr(HTTPStatus, name, None)
378
+ return None if found is None else int(found)
379
+ case _:
380
+ return None
381
+ return None
@@ -0,0 +1,10 @@
1
+ """Ошибки.
2
+
3
+ Отказ, который модуль говорит наружу, несёт код: фраза — человеку, код — тому,
4
+ кто на него ветвится.
5
+ """
6
+
7
+ from py_checks.checks.errors._marker import MARKER
8
+ from py_checks.checks.errors._refusals import Refusals, RefusalsSettings
9
+
10
+ __all__ = ["MARKER", "Refusals", "RefusalsSettings"]
@@ -0,0 +1,5 @@
1
+ """Слово группы для пометок: `# error-ok: <код>: <причина>`."""
2
+
3
+ from typing import Final
4
+
5
+ MARKER: Final = "# error-ok"