python-checks 0.4.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

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 (117) hide show
  1. py_checks/checks/__init__.py +15 -14
  2. py_checks/checks/_kind.py +34 -32
  3. py_checks/checks/_layout.py +75 -68
  4. py_checks/checks/_location.py +53 -31
  5. py_checks/checks/_names.py +25 -23
  6. py_checks/checks/api/__init__.py +12 -7
  7. py_checks/checks/api/_edge_declarations.py +388 -0
  8. py_checks/checks/api/_marker.py +1 -1
  9. py_checks/checks/calls/__init__.py +3 -3
  10. py_checks/checks/calls/_confined_functions.py +15 -14
  11. py_checks/checks/calls/_marker.py +1 -1
  12. py_checks/checks/database/__init__.py +7 -5
  13. py_checks/checks/database/_bound_checks.py +32 -31
  14. py_checks/checks/database/_confined_calls.py +23 -23
  15. py_checks/checks/database/_marker.py +1 -1
  16. py_checks/checks/database/_model_boundary.py +37 -36
  17. py_checks/checks/database/_model_columns.py +36 -36
  18. py_checks/checks/database/_raw_sql.py +40 -37
  19. py_checks/checks/database/_schema_drift.py +50 -47
  20. py_checks/checks/database/_statement_keys.py +29 -28
  21. py_checks/checks/effects/__init__.py +6 -5
  22. py_checks/checks/effects/_determinism.py +26 -23
  23. py_checks/checks/effects/_log_events.py +18 -18
  24. py_checks/checks/effects/_marker.py +1 -1
  25. py_checks/checks/errors/__init__.py +10 -0
  26. py_checks/checks/errors/_marker.py +5 -0
  27. py_checks/checks/errors/_refusals.py +160 -0
  28. py_checks/checks/hygiene/__init__.py +5 -4
  29. py_checks/checks/hygiene/_dependency_bounds.py +33 -33
  30. py_checks/checks/hygiene/_marker.py +1 -1
  31. py_checks/checks/imports/__init__.py +9 -9
  32. py_checks/checks/imports/_confined.py +15 -14
  33. py_checks/checks/imports/_marker.py +1 -1
  34. py_checks/checks/imports/_sealed.py +17 -28
  35. py_checks/checks/imports/_statements.py +5 -5
  36. py_checks/checks/placement/__init__.py +11 -11
  37. py_checks/checks/placement/_class_modules.py +17 -15
  38. py_checks/checks/placement/_class_placement.py +16 -15
  39. py_checks/checks/placement/_marker.py +1 -1
  40. py_checks/checks/placement/_operation_shape.py +56 -54
  41. py_checks/checks/placement/_required_class.py +28 -28
  42. py_checks/checks/signatures/__init__.py +6 -5
  43. py_checks/checks/signatures/_function_length.py +18 -17
  44. py_checks/checks/signatures/_functions.py +13 -12
  45. py_checks/checks/signatures/_keyword_only.py +23 -21
  46. py_checks/checks/signatures/_marker.py +1 -1
  47. py_checks/checks/signatures/_module_length.py +8 -8
  48. py_checks/checks/signatures/_nesting.py +20 -20
  49. py_checks/checks/signatures/_signature_layout.py +46 -47
  50. py_checks/checks/types/__init__.py +5 -4
  51. py_checks/checks/types/_annotation_shapes.py +20 -20
  52. py_checks/checks/types/_config_fields.py +44 -43
  53. py_checks/checks/types/_confined_types.py +26 -26
  54. py_checks/checks/types/_constant_annotations.py +18 -17
  55. py_checks/checks/types/_frozen_dataclasses.py +14 -13
  56. py_checks/checks/types/_marker.py +1 -1
  57. py_checks/cli/__init__.py +3 -3
  58. py_checks/cli/_app.py +3 -3
  59. py_checks/cli/_protocols.py +6 -5
  60. py_checks/cli/commands/__init__.py +6 -4
  61. py_checks/cli/commands/_doctor.py +81 -67
  62. py_checks/cli/commands/_explain.py +15 -14
  63. py_checks/cli/commands/_list.py +10 -10
  64. py_checks/cli/commands/_mutation.py +247 -0
  65. py_checks/cli/commands/_run.py +25 -26
  66. py_checks/cli/commands/_summary.py +3 -3
  67. py_checks/cli/commands/_sync.py +9 -9
  68. py_checks/config/__init__.py +7 -7
  69. py_checks/config/_base.py +11 -10
  70. py_checks/config/_config.py +68 -31
  71. py_checks/config/_constants.py +7 -7
  72. py_checks/config/_errors.py +5 -5
  73. py_checks/config/_loader.py +22 -21
  74. py_checks/config/_toml.py +5 -4
  75. py_checks/contracts/__init__.py +9 -9
  76. py_checks/contracts/_constants.py +4 -4
  77. py_checks/contracts/_layout.py +7 -6
  78. py_checks/contracts/_render.py +26 -25
  79. py_checks/contracts/_settings.py +11 -11
  80. py_checks/core/__init__.py +4 -4
  81. py_checks/core/_constants.py +7 -6
  82. py_checks/core/_discovery.py +6 -6
  83. py_checks/core/_edit.py +18 -15
  84. py_checks/core/_errors.py +4 -4
  85. py_checks/core/_fixer.py +5 -5
  86. py_checks/core/_format.py +7 -7
  87. py_checks/core/_markers.py +41 -37
  88. py_checks/core/_paths.py +14 -12
  89. py_checks/core/_protocols.py +33 -29
  90. py_checks/core/_registry.py +15 -13
  91. py_checks/core/_report.py +8 -7
  92. py_checks/core/_runner.py +18 -18
  93. py_checks/core/_settings.py +8 -8
  94. py_checks/core/_source.py +14 -13
  95. py_checks/core/_violation.py +15 -13
  96. py_checks/environment/__init__.py +6 -6
  97. py_checks/environment/_constants.py +1 -1
  98. py_checks/environment/_render.py +38 -37
  99. py_checks/environment/_settings.py +11 -10
  100. py_checks/mutation/__init__.py +34 -0
  101. py_checks/mutation/_baseline.py +47 -0
  102. py_checks/mutation/_constants.py +11 -0
  103. py_checks/mutation/_errors.py +12 -0
  104. py_checks/mutation/_gate.py +175 -0
  105. py_checks/mutation/_mutmut.py +162 -0
  106. py_checks/mutation/_process.py +44 -0
  107. py_checks/mutation/_scope.py +155 -0
  108. py_checks/mutation/_settings.py +54 -0
  109. py_checks/sync/__init__.py +9 -9
  110. py_checks/sync/_sync.py +11 -10
  111. {python_checks-0.4.2.dist-info → python_checks-0.6.0.dist-info}/METADATA +9 -4
  112. python_checks-0.6.0.dist-info/RECORD +117 -0
  113. {python_checks-0.4.2.dist-info → python_checks-0.6.0.dist-info}/WHEEL +1 -1
  114. {python_checks-0.4.2.dist-info → python_checks-0.6.0.dist-info}/entry_points.txt +2 -1
  115. py_checks/checks/api/_endpoint_declarations.py +0 -204
  116. python_checks-0.4.2.dist-info/RECORD +0 -104
  117. {python_checks-0.4.2.dist-info → python_checks-0.6.0.dist-info}/licenses/LICENSE +0 -0
@@ -1,8 +1,9 @@
1
- """Имена: как их читают в дереве и как сверяют с записанным в настройках.
1
+ """Names: how they are read in the tree and matched against the settings.
2
2
 
3
- Правила говорят именами: «база называется `Base`», «эта колонка объявлена
4
- `mapped_column`», «`datetime.now` берут портом». Спросить у узла, как его
5
- зовут, — не дело каждого правила: способ один на язык, и живёт он здесь.
3
+ Rules speak in names: "the base is called `Base`", "this column is declared
4
+ with `mapped_column`", "`datetime.now` is taken as a port". Asking a node what
5
+ it is called is not every rule's business: there is one way per language, and
6
+ it lives here.
6
7
  """
7
8
 
8
9
  from __future__ import annotations
@@ -18,13 +19,14 @@ ANY: Final = "*"
18
19
 
19
20
 
20
21
  def name(*, node: ast.expr) -> str:
21
- """Как это зовут; пустая строка, если именем это не назвать.
22
-
23
- Строковая аннотация (`-> "Order"`) — это имя, написанное буквами:
24
- отличать её от обычной незачем, автор имел в виду то же самое. А вот вызов
25
- и подписанное выражение именем не считаются: `tuple(...)[:1]` — это срез
26
- списка, и правило про формы типов не должно принять его за объявление.
27
- Развернуть их просит тот, кто читает базы и декораторы, — `names`.
22
+ """What this is called; an empty string if it cannot be called by a name.
23
+
24
+ A string annotation (`-> "Order"`) is a name spelled out in letters: there
25
+ is no reason to tell it from an ordinary one, the author meant the same
26
+ thing. A call and a subscript, though, do not count as names:
27
+ `tuple(...)[:1]` is a slice of a list, and a rule about type shapes must not
28
+ take it for a declaration. Unwrapping them is asked for by whoever reads
29
+ bases and decorators — `names`.
28
30
  """
29
31
  match node:
30
32
  case ast.Name(id=found) | ast.Attribute(attr=found) | ast.Constant(value=str() as found):
@@ -34,10 +36,10 @@ def name(*, node: ast.expr) -> str:
34
36
 
35
37
 
36
38
  def names(*, nodes: Iterable[ast.expr]) -> Iterator[str]:
37
- """Имена перечисленного: баз класса, декораторов.
39
+ """The names of what is listed: a class's bases, decorators.
38
40
 
39
- Здесь имя и правда стоит за вызовом и за подстановкой: `@dataclass(frozen=True)`
40
- — это `dataclass`, `Generic[T]` — это `Generic`.
41
+ Here the name really does stand behind a call and a subscript:
42
+ `@dataclass(frozen=True)` is `dataclass`, `Generic[T]` is `Generic`.
41
43
  """
42
44
  for node in nodes:
43
45
  if found := name(node=_head(node=node)):
@@ -45,7 +47,7 @@ def names(*, nodes: Iterable[ast.expr]) -> Iterator[str]:
45
47
 
46
48
 
47
49
  def _head(*, node: ast.expr) -> ast.expr:
48
- """Из чего сделано выражение: с кого начали, прежде чем звать и подставлять."""
50
+ """What an expression is made of: what it started from before calls and subscripts."""
49
51
  match node:
50
52
  case ast.Call(func=inner) | ast.Subscript(value=inner):
51
53
  return _head(node=inner)
@@ -54,12 +56,12 @@ def _head(*, node: ast.expr) -> ast.expr:
54
56
 
55
57
 
56
58
  def walked(*, node: ast.expr) -> Iterator[str]:
57
- """Все имена внутри выражения, на любой глубине и в порядке написания.
59
+ """Every name inside an expression, at any depth and in written order.
58
60
 
59
- `dict[str, Order | None]` — это `dict`, `str`, `Order`: правило про
60
- аннотации смотрит на то, что в ней названо, а не на её форму. Имя, взятое
61
- в кавычки, — такое же имя: ссылка вперёд написана строкой не по смыслу, а
62
- потому что в этом месте класса ещё нет.
61
+ `dict[str, Order | None]` is `dict`, `str`, `Order`: a rule about
62
+ annotations looks at what is named in one, not at its shape. A name in
63
+ quotes is the same name: a forward reference is written as a string not
64
+ for meaning, but because the class does not exist yet at that point.
63
65
  """
64
66
  for child in ast.walk(node):
65
67
  if isinstance(child, ast.Name | ast.Attribute | ast.Constant) and (
@@ -73,10 +75,10 @@ def matches(
73
75
  called: str,
74
76
  pattern: str,
75
77
  ) -> bool:
76
- """Хвост имени: `datetime.now` — это и `datetime.datetime.now`.
78
+ """The tail of a name: `datetime.now` is also `datetime.datetime.now`.
77
79
 
78
- `random.*` подходит любому вызову модуля целиком: важен не последний
79
- кусок, а то, у кого его взяли.
80
+ `random.*` matches any call of the whole module: what matters is not the
81
+ last part but what it was taken from.
80
82
  """
81
83
  parts = called.split(DOT)
82
84
  wanted = pattern.split(DOT)
@@ -1,13 +1,18 @@
1
- """API и события.
1
+ """API and events.
2
2
 
3
- Маршрут объявляет в декораторе всё, чем он будет описан в схеме: механизм у
4
- фреймворка есть, требования писать — нет.
3
+ An entrance into the process declares in its decorator everything that was
4
+ decided for it: the framework has the mechanism but does not demand it, and
5
+ each of its defaults is a decision made by somebody other than this project.
5
6
  """
6
7
 
7
- from py_checks.checks.api._endpoint_declarations import (
8
- EndpointDeclarations,
9
- EndpointDeclarationsSettings,
8
+ from py_checks.checks.api._edge_declarations import (
9
+ KNOWN,
10
+ Edge,
11
+ EdgeDeclarations,
12
+ Edges,
13
+ Framework,
14
+ Shape,
10
15
  )
11
16
  from py_checks.checks.api._marker import MARKER
12
17
 
13
- __all__ = ["MARKER", "EndpointDeclarations", "EndpointDeclarationsSettings"]
18
+ __all__ = ["KNOWN", "MARKER", "Edge", "EdgeDeclarations", "Edges", "Framework", "Shape"]
@@ -0,0 +1,388 @@
1
+ """An entrance into the process declares in its decorator everything decided for it."""
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
+ """The framework an entrance is written with."""
29
+
30
+ FASTAPI = "fastapi"
31
+ FASTSTREAM = "faststream"
32
+
33
+
34
+ @dataclass(frozen=True, slots=True)
35
+ class Shape:
36
+ """How a framework writes an entrance. This is the library's knowledge, not the project's.
37
+
38
+ The project decides what an entrance must declare; what an "entrance" is
39
+ in FastAPI and in FastStream was decided by their authors, and a table the
40
+ project wrote about it would be a retelling of somebody else's
41
+ documentation, going stale along with it.
42
+ """
43
+
44
+ # The method names an entrance is declared with: `broker.subscriber`,
45
+ # `router.post`. The object name on the left is not read — it is a variable
46
+ # name, and a rule about what a variable is called would be a rule about
47
+ # spelling.
48
+ methods: tuple[str, ...]
49
+
50
+ # Only as a decorator. For a route this is a must: its `methods` are `get`,
51
+ # `post`, `delete`, the same names an HTTP client goes by, and a rule
52
+ # reading every `.post(...)` would find a route in the first adapter that
53
+ # talks to a neighbouring service. A subscription cannot be mistaken for
54
+ # anything like that, and it is written both as a decorator and as a call:
55
+ # it is kept in a variable and applied to the handler separately, because
56
+ # its client is taken before the start.
57
+ decorated: bool
58
+
59
+ # The word a message uses for the first argument.
60
+ subject: str
61
+
62
+ # The first argument's name if it is written by keyword; `None` — positional.
63
+ named: str | None
64
+
65
+ # The argument declaring the response body, and the statuses that never have one.
66
+ body: str | None = None
67
+ bodiless: tuple[int, ...] = ()
68
+
69
+ # The flag an entrance uses to say it is not in the schema.
70
+ exempt: str | None = None
71
+
72
+
73
+ KNOWN: Final[dict[str, Shape]] = {
74
+ Framework.FASTAPI: Shape(
75
+ methods=("get", "post", "put", "patch", "delete", "head", "options", "trace"),
76
+ decorated=True,
77
+ subject="path",
78
+ named="path",
79
+ body="response_model",
80
+ bodiless=(
81
+ int(HTTPStatus.NO_CONTENT),
82
+ int(HTTPStatus.RESET_CONTENT),
83
+ int(HTTPStatus.NOT_MODIFIED),
84
+ ),
85
+ exempt="include_in_schema",
86
+ ),
87
+ Framework.FASTSTREAM: Shape(
88
+ methods=("subscriber",),
89
+ decorated=False,
90
+ subject="topic",
91
+ named=None,
92
+ ),
93
+ }
94
+
95
+
96
+ class Edge(CheckSettings):
97
+ """What an entrance of this framework must name.
98
+
99
+ Every name here is a decision that has a default in the framework's
100
+ library, and that default was made by somebody other than whoever writes
101
+ the service.
102
+ """
103
+
104
+ required: tuple[str, ...] = ()
105
+
106
+
107
+ class Edges(CheckSettings):
108
+ """The entrance table: one block per framework.
109
+
110
+ ```toml
111
+ [edge-declarations.fastapi]
112
+ required = ["path", "status_code", "summary", "responses"]
113
+
114
+ [edge-declarations.faststream]
115
+ required = ["group_id", "parser", "decoder", "ack_policy"]
116
+ ```
117
+ """
118
+
119
+ model_config = OPEN
120
+ __pydantic_extra__: dict[str, Edge] # type: ignore[assignment]
121
+
122
+ @model_validator(mode="after")
123
+ def _known(self) -> Self:
124
+ """A block's name is a framework the library knows something about."""
125
+ unknown = sorted(set(self.frameworks) - set(KNOWN))
126
+ if unknown:
127
+ listed = ", ".join(repr(name) for name in unknown)
128
+ known = ", ".join(sorted(KNOWN))
129
+ message = f"{listed}: the rule does not know this framework; it knows {known}"
130
+ raise ValueError(message)
131
+ return self
132
+
133
+ @property
134
+ def frameworks(self) -> dict[str, Edge]:
135
+ return self.__pydantic_extra__
136
+
137
+
138
+ class EdgeDeclarations:
139
+ """Fails when an entrance into the process did not say how it behaves.
140
+
141
+ An entrance's decorator is a contract. For a route it is read by whoever
142
+ reads the generated schema — a neighbouring service, a person writing a
143
+ client — and a field that is not in the decorator does not exist for them,
144
+ whatever the function body returns. For a subscription it is read by
145
+ whoever is working out why a record was handled twice or not at all.
146
+
147
+ The framework has the mechanism but demands none of it, and each default
148
+ there is a decision made by somebody other than this project. A route with
149
+ no `summary` lands in the schema with the function's name in place of a
150
+ description, and with an empty `responses` it lands with a promise that it
151
+ never refuses. A subscription with no `ack_policy` hands the broker back
152
+ the record it has just delivered, and with no `auto_offset_reset` it skips
153
+ the backlog a new group exists to read.
154
+
155
+ The library knows what an entrance is in FastAPI and in FastStream: the
156
+ method names, whether it is a decorator or a call, how the first argument
157
+ is written. The project names one thing: what an entrance must declare.
158
+
159
+ The body is declared apart from the rest and is not required where there
160
+ is none: 204, 205 and 304 are statuses without a body, and a response
161
+ model next to them promises what the protocol forbids. A status written as
162
+ neither a number nor an `HTTPStatus` member reads as unknown, and an
163
+ unknown one is taken to have a body: a check that fired needlessly is
164
+ lifted by a mark, while one that stayed silent is a contract nobody will
165
+ miss.
166
+
167
+ An entrance taken out of the schema (`include_in_schema=False`) the rule
168
+ leaves alone: the schema is what it protects, and such a route is not in it.
169
+
170
+ Settings: one block per framework, with `required` in it.
171
+ """
172
+
173
+ code: ClassVar[str] = CODE
174
+ Settings: ClassVar[type[CheckSettings]] = Edges
175
+ scope: ClassVar[Scope] = Scope.FILE
176
+ marker: ClassVar[str] = MARKER
177
+
178
+ @classmethod
179
+ def run(
180
+ cls,
181
+ *,
182
+ file: ParsedFile,
183
+ settings: CheckSettings,
184
+ ) -> Iterator[Violation]:
185
+ frameworks = settings_as(
186
+ settings=settings,
187
+ model=Edges,
188
+ code=CODE,
189
+ ).frameworks
190
+ decorators = cls._decorators(tree=file.tree)
191
+ for node in ast.walk(file.tree):
192
+ if not isinstance(node, ast.Call):
193
+ continue
194
+ found = cls._matched(
195
+ call=node,
196
+ frameworks=frameworks,
197
+ )
198
+ if found is None:
199
+ continue
200
+ shape, edge = found
201
+ if shape.decorated and node not in decorators:
202
+ continue
203
+ yield from cls._judged(
204
+ call=node,
205
+ file=file,
206
+ shape=shape,
207
+ edge=edge,
208
+ )
209
+
210
+ @staticmethod
211
+ def _decorators(*, tree: ast.Module) -> set[ast.Call]:
212
+ """Calls that stand as a decorator: for such an entrance anything else is not it."""
213
+ return {
214
+ decorator
215
+ for node in ast.walk(tree)
216
+ if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)
217
+ for decorator in node.decorator_list
218
+ if isinstance(decorator, ast.Call)
219
+ }
220
+
221
+ @staticmethod
222
+ def _matched(
223
+ *,
224
+ call: ast.Call,
225
+ frameworks: dict[str, Edge],
226
+ ) -> tuple[Shape, Edge] | None:
227
+ """Which framework's entrance is declared here; `None` — not an entrance."""
228
+ if not isinstance(call.func, ast.Attribute):
229
+ return None
230
+ for name, edge in frameworks.items():
231
+ shape = KNOWN[name]
232
+ if call.func.attr in shape.methods:
233
+ return shape, edge
234
+ return None
235
+
236
+ @classmethod
237
+ def _judged(
238
+ cls,
239
+ *,
240
+ call: ast.Call,
241
+ file: ParsedFile,
242
+ shape: Shape,
243
+ edge: Edge,
244
+ ) -> Iterator[Violation]:
245
+ if cls._unpublished(
246
+ call=call,
247
+ exempt=shape.exempt,
248
+ ):
249
+ return
250
+ named = cls._name(
251
+ call=call,
252
+ shape=shape,
253
+ )
254
+ declared = {keyword.arg for keyword in call.keywords}
255
+ yield from cls._first(
256
+ call=call,
257
+ file=file,
258
+ shape=shape,
259
+ named=named,
260
+ )
261
+ for wanted in edge.required:
262
+ # One written positionally where it should not be was named above
263
+ # already; a second remark about the same entrance reads as a second miss.
264
+ if wanted in declared or (wanted == shape.named and call.args):
265
+ continue
266
+ yield cls._violation(
267
+ call=call,
268
+ file=file,
269
+ message=f"{named} does not declare {wanted}=",
270
+ )
271
+ yield from cls._bodied(
272
+ call=call,
273
+ file=file,
274
+ shape=shape,
275
+ declared=declared,
276
+ named=named,
277
+ )
278
+
279
+ @classmethod
280
+ def _first(
281
+ cls,
282
+ *,
283
+ call: ast.Call,
284
+ file: ParsedFile,
285
+ shape: Shape,
286
+ named: str,
287
+ ) -> Iterator[Violation]:
288
+ """The first argument: written the wrong way, or not written at all."""
289
+ if shape.named is not None:
290
+ if call.args:
291
+ yield cls._violation(
292
+ call=call,
293
+ file=file,
294
+ message=f"{named} gives the {shape.subject} positionally; write {shape.named}=",
295
+ )
296
+ return
297
+ if not call.args:
298
+ yield cls._violation(
299
+ call=call,
300
+ file=file,
301
+ message=f"{named} does not name the {shape.subject}; it goes first, without a name",
302
+ )
303
+
304
+ @classmethod
305
+ def _bodied(
306
+ cls,
307
+ *,
308
+ call: ast.Call,
309
+ file: ParsedFile,
310
+ shape: Shape,
311
+ declared: set[str | None],
312
+ named: str,
313
+ ) -> Iterator[Violation]:
314
+ if shape.body is None or shape.body in declared:
315
+ return
316
+ if cls._status(call=call) in shape.bodiless:
317
+ return
318
+ yield cls._violation(
319
+ call=call,
320
+ file=file,
321
+ message=(
322
+ f"{named} does not declare {shape.body}= and answers with a body; "
323
+ f"only {', '.join(str(status) for status in shape.bodiless)} go without it"
324
+ ),
325
+ )
326
+
327
+ @staticmethod
328
+ def _violation(
329
+ *,
330
+ call: ast.Call,
331
+ file: ParsedFile,
332
+ message: str,
333
+ ) -> Violation:
334
+ return Violation.from_node(
335
+ node=call,
336
+ path=file.path,
337
+ code=CODE,
338
+ message=message,
339
+ )
340
+
341
+ @staticmethod
342
+ def _unpublished(
343
+ *,
344
+ call: ast.Call,
345
+ exempt: str | None,
346
+ ) -> bool:
347
+ """The entrance said it is not in the schema."""
348
+ return exempt is not None and any(
349
+ keyword.arg == exempt
350
+ and isinstance(keyword.value, ast.Constant)
351
+ and keyword.value.value is False
352
+ for keyword in call.keywords
353
+ )
354
+
355
+ @staticmethod
356
+ def _name(
357
+ *,
358
+ call: ast.Call,
359
+ shape: Shape,
360
+ ) -> str:
361
+ """`POST '/tickets'`, `SUBSCRIBER 'bets.placed'` — however it is written.
362
+
363
+ The subject of the declaration is read both from the position and from
364
+ the keyword: a message has to name the entrance even in a file where
365
+ the keyword is missing — "GET does not declare summary" in a module
366
+ with six GETs names nothing.
367
+ """
368
+ attribute = call.func
369
+ method = attribute.attr.upper() if isinstance(attribute, ast.Attribute) else ""
370
+ written = [keyword.value for keyword in call.keywords if keyword.arg == shape.named]
371
+ subject = call.args[:1] + written
372
+ return f"{method} {ast.unparse(subject[0])}" if subject else method
373
+
374
+ @staticmethod
375
+ def _status(*, call: ast.Call) -> int | None:
376
+ """The status, if it is written so that the file shows it."""
377
+ for keyword in call.keywords:
378
+ if keyword.arg != STATUS:
379
+ continue
380
+ match keyword.value:
381
+ case ast.Constant(value=int() as status):
382
+ return status
383
+ case ast.Attribute(value=ast.Name(id="HTTPStatus"), attr=name):
384
+ found = getattr(HTTPStatus, name, None)
385
+ return None if found is None else int(found)
386
+ case _:
387
+ return None
388
+ return None
@@ -1,4 +1,4 @@
1
- """Слово группы для пометок: `# api-ok: <код>: <причина>`."""
1
+ """The group's word for marks: `# api-ok: <code>: <reason>`."""
2
2
 
3
3
  from typing import Final
4
4
 
@@ -1,7 +1,7 @@
1
- """Места вызова.
1
+ """Call sites.
2
2
 
3
- Есть функции, у которых законных мест вызова ровно столько, сколько их
4
- перечислено: конверсия денег, например. Правило держит этот список.
3
+ Some functions have exactly as many lawful call sites as are listed: money
4
+ conversion, for one. The rule holds that list.
5
5
  """
6
6
 
7
7
  from py_checks.checks.calls._confined_functions import (
@@ -1,4 +1,4 @@
1
- """У некоторых функций законных мест вызова ровно столько, сколько перечислено."""
1
+ """Some functions have exactly as many lawful call sites as are listed."""
2
2
 
3
3
  from __future__ import annotations
4
4
 
@@ -20,26 +20,27 @@ CODE: Final = "confined-functions"
20
20
 
21
21
 
22
22
  class ConfinedFunctionsSettings(CheckSettings):
23
- calls: dict[str, tuple[str, ...]] = {} # noqa: RUF012 — pydantic копирует значение сам
23
+ calls: dict[str, tuple[str, ...]] = {} # noqa: RUF012 — pydantic copies the value itself
24
24
  declared_in: str | None = None
25
25
 
26
26
 
27
27
  class ConfinedFunctions:
28
- """Падает, если названная функция позвана не оттуда, откуда ей можно.
28
+ """Fails if a named function is called from somewhere it may not be.
29
29
 
30
- Написано ради конверсии денег. Сервис считает в одной валюте, и гарантия
31
- за этой фразой — не имя типа: это то, что у конверсии одна реализация и
32
- места её вызова можно перечислить. Где угодно ещё конверсия — это сумма в
33
- чьей-то валюте посреди расчёта, и ошибка, которую она даёт, — число,
34
- верное ровно до того дня, когда встретятся две валюты.
30
+ Written for money conversion. A service counts in one currency, and the
31
+ guarantee behind that sentence is not the name of a type: it is that
32
+ conversion has one implementation and its call sites can be listed.
33
+ Anywhere else, a conversion is an amount in somebody's currency in the
34
+ middle of a calculation, and the error it gives is a number that is right
35
+ up to the day two currencies meet.
35
36
 
36
- Место — кусок пути, а не файл: край — это место в замысле, и файл, который
37
- разделили надвое, краем быть не перестал.
37
+ A place is a piece of a path, not a file: an edge is a place in the design,
38
+ and a file split in two has not stopped being an edge.
38
39
 
39
- `declared-in` — модуль, где функция объявлена: там она написана, а не позвана, и
40
- правило его не трогает.
40
+ `declared-in` is the module where the function is declared: there it is
41
+ written, not called, and the rule leaves it alone.
41
42
 
42
- Настройки: `calls`, `declared-in`.
43
+ Settings: `calls`, `declared-in`.
43
44
  """
44
45
 
45
46
  code: ClassVar[str] = CODE
@@ -80,7 +81,7 @@ class ConfinedFunctions:
80
81
  node=node,
81
82
  path=file.path,
82
83
  code=CODE,
83
- message=f"{called}() зовут не отсюда; её места — {', '.join(allowed)}",
84
+ message=f"{called}() is not called from here; its places are {', '.join(allowed)}",
84
85
  )
85
86
 
86
87
  @staticmethod
@@ -1,4 +1,4 @@
1
- """Слово группы для пометок: `# call-ok: <код>: <причина>`."""
1
+ """The group's word for marks: `# call-ok: <code>: <reason>`."""
2
2
 
3
3
  from typing import Final
4
4
 
@@ -1,9 +1,11 @@
1
- """База данных.
1
+ """The database.
2
2
 
3
- Граница транзакции, материал колонки, форма запроса. Готового тут почти нет:
4
- `pytest-alembic` отвечает на откат миграции, `alembic check` — на расхождение
5
- моделей и миграций, но звать его приходится самим: ему нужна живая база,
6
- поэтому `schema-drift` объявлен `ENVIRONMENT`. Остальное — соглашения проекта.
3
+ The transaction boundary, the material of a column, the shape of a statement.
4
+ Little of this exists off the shelf: `pytest-alembic` answers for rolling a
5
+ migration back, `alembic check` for models and migrations disagreeing, but
6
+ somebody has to call it: it needs a live database, which is why
7
+ `schema-drift` is declared `ENVIRONMENT`. The rest is the project's own
8
+ conventions.
7
9
  """
8
10
 
9
11
  from py_checks.checks.database._bound_checks import BoundChecks, BoundChecksSettings