python-checks 0.4.2__py3-none-any.whl → 0.5.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.
@@ -1,13 +1,18 @@
1
1
  """API и события.
2
2
 
3
- Маршрут объявляет в декораторе всё, чем он будет описан в схеме: механизм у
4
- фреймворка есть, требования писать — нет.
3
+ Вход в процесс объявляет в декораторе всё, что за него решили: механизм у
4
+ фреймворка есть, требования писать — нет, а каждое его умолчание — решение,
5
+ принятое не этим проектом.
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,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"
@@ -0,0 +1,159 @@
1
+ """Отказ, на который вызывающему нечем ответить, — это не отказ, а падение."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ast
6
+ import builtins
7
+ from typing import TYPE_CHECKING, ClassVar, Final
8
+
9
+ from py_checks.checks._location import ZonedSettings, zoned
10
+ from py_checks.checks._names import name
11
+ from py_checks.checks.errors._marker import MARKER
12
+ from py_checks.core import Scope, Violation, settings_as
13
+
14
+ if TYPE_CHECKING:
15
+ from collections.abc import Iterator
16
+
17
+ from py_checks.config import CheckSettings
18
+ from py_checks.core import ParsedFile
19
+
20
+ CODE: Final = "refusals"
21
+
22
+ # Исключения, которые везёт сам интерпретатор, — по именам. Читаются из
23
+ # `builtins`, а не перечисляются: список пришлось бы кому-то поддерживать, а
24
+ # он меняется от версии к версии языка.
25
+ BUILTINS: Final[frozenset[str]] = frozenset(
26
+ found
27
+ for found, value in vars(builtins).items()
28
+ if isinstance(value, type) and issubclass(value, BaseException)
29
+ )
30
+
31
+
32
+ class RefusalsSettings(ZonedSettings):
33
+ """Где судим, чем несут код и что отказом не считается.
34
+
35
+ `carries` не назван — у проекта нет своего кода отказа, и правило судит
36
+ только встроенные исключения: у них кода нет ни в каком виде. Назван —
37
+ своя ошибка обязана нести его с собой, кроме перечисленных в `internal`.
38
+ """
39
+
40
+ carries: str | None = None
41
+ allow: tuple[str, ...] = ()
42
+ internal: tuple[str, ...] = ()
43
+
44
+
45
+ class Refusals:
46
+ """Падает, если отказ выходит наружу без кода, на который можно ветвиться.
47
+
48
+ У отказа две половины. Фраза — человеку: её читают в логе, её переписывают,
49
+ и зависеть от её слов нельзя ничему. Код — то, на что ветвится вызывающий:
50
+ «денег не хватило» — это экран, «купон изменился» — это пересчёт. Поэтому
51
+ фраза вольна меняться, а код нет, и держится это ровно до тех пор, пока
52
+ каждое «нет», которое говорит модуль, несёт его с собой.
53
+
54
+ Встроенное исключение кода не несёт вовсе. `ValueError`, пересёкший
55
+ сценарий, — это отказ, о котором снаружи известно только то, что он
56
+ случился, и периметр честно превращает его в 500: больше ему сделать не из
57
+ чего. Что из встроенных отказом не считается, говорит `allow`:
58
+ `NotImplementedError` — это не «нет», а метод, которого ещё нет, и
59
+ единственное исключение, которое читатель не спутает с ответом.
60
+
61
+ Своя ошибка кодом обязана, если она про игрока. Та, что говорит «код
62
+ написан неверно» или «порт нарушил обещание», — внутренняя, ветвиться на
63
+ неё некому, и её имена перечисляет `internal`.
64
+
65
+ Настройки: `zones`, `carries`, `allow`, `internal`.
66
+ """
67
+
68
+ code: ClassVar[str] = CODE
69
+ Settings: ClassVar[type[CheckSettings]] = RefusalsSettings
70
+ scope: ClassVar[Scope] = Scope.FILE
71
+ marker: ClassVar[str] = MARKER
72
+
73
+ @classmethod
74
+ def run(
75
+ cls,
76
+ *,
77
+ file: ParsedFile,
78
+ settings: CheckSettings,
79
+ ) -> Iterator[Violation]:
80
+ limits = settings_as(
81
+ settings=settings,
82
+ model=RefusalsSettings,
83
+ code=CODE,
84
+ )
85
+ where = zoned(
86
+ file=file,
87
+ zones=limits.zones,
88
+ )
89
+ if where is None:
90
+ return
91
+ # По строкам, а не по обходу: `ast.walk` идёт в ширину, и отказ из
92
+ # глубины `if` оказывается в выводе позже соседа, написанного ниже.
93
+ yield from sorted(
94
+ cls._found(
95
+ file=file,
96
+ limits=limits,
97
+ ),
98
+ key=lambda violation: (violation.line, violation.column),
99
+ )
100
+
101
+ @classmethod
102
+ def _found(
103
+ cls,
104
+ *,
105
+ file: ParsedFile,
106
+ limits: RefusalsSettings,
107
+ ) -> Iterator[Violation]:
108
+ for node in ast.walk(file.tree):
109
+ if not isinstance(node, ast.Raise) or node.exc is None:
110
+ continue
111
+ raised = cls._raised(thrown=node.exc)
112
+ if not raised:
113
+ continue
114
+ found = cls._said(
115
+ raised=raised,
116
+ thrown=node.exc,
117
+ limits=limits,
118
+ )
119
+ if found is None:
120
+ continue
121
+ yield Violation.from_node(
122
+ node=node,
123
+ path=file.path,
124
+ code=CODE,
125
+ message=found,
126
+ )
127
+
128
+ @staticmethod
129
+ def _raised(*, thrown: ast.expr) -> str:
130
+ """Что брошено: `raise Denied(...)` и `raise Denied` — одно и то же имя."""
131
+ return name(node=thrown.func) if isinstance(thrown, ast.Call) else name(node=thrown)
132
+
133
+ @classmethod
134
+ def _said(
135
+ cls,
136
+ *,
137
+ raised: str,
138
+ thrown: ast.expr,
139
+ limits: RefusalsSettings,
140
+ ) -> str | None:
141
+ """Чем плох этот `raise`; `None` — ничем."""
142
+ if raised in BUILTINS:
143
+ if raised in limits.allow:
144
+ return None
145
+ said = f" с {limits.carries}=" if limits.carries else ""
146
+ return (
147
+ f"бросает {raised}, а кода на нём нет: снаружи об этом отказе известно "
148
+ f"только то, что он случился. Ответь своей ошибкой{said}"
149
+ )
150
+ if limits.carries is None or raised in limits.internal:
151
+ return None
152
+ if not isinstance(thrown, ast.Call):
153
+ return f"бросает {raised} классом, без {limits.carries}="
154
+ if any(keyword.arg == limits.carries for keyword in thrown.keywords):
155
+ return None
156
+ return (
157
+ f"бросает {raised} без {limits.carries}=; код — то, на что ветвится "
158
+ f"вызывающий, а фраза — человеку"
159
+ )
@@ -2,6 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from dataclasses import dataclass
5
6
  from pathlib import Path
6
7
  from typing import TYPE_CHECKING, Final
7
8
 
@@ -16,16 +17,46 @@ if TYPE_CHECKING:
16
17
  from collections.abc import Mapping
17
18
 
18
19
 
19
- # Секции, которые больше не читаются: четыре правила про раскладку говорили об
20
- # одной и той же директории с четырёх сторон, и один факт приходилось писать
21
- # четыре раза. Молчать о них нельзя — незнакомая секция выглядит как
22
- # работающая настройка, а на деле правило судит по пустой таблице.
23
- RETIRED: Final[dict[str, str]] = {
24
- "class-modules": "`only`",
25
- "class-placement": "`home` и `suffix`",
26
- "required-class": "`required` рядом с `suffix`",
27
- "operation-shape": "`operation`",
28
- "model-boundary": "`orm` и `base`",
20
+ @dataclass(frozen=True, slots=True)
21
+ class Moved:
22
+ """Куда переехала секция и чем она там записывается."""
23
+
24
+ into: str
25
+ written: str
26
+
27
+
28
+ # Секции, которые больше не читаются. Молчать о них нельзя: незнакомая секция
29
+ # выглядит как работающая настройка, а на деле правило судит по пустой таблице.
30
+ #
31
+ # Четыре правила про раскладку говорили об одной директории с четырёх сторон, и
32
+ # один факт приходилось писать четыре раза в четырёх синтаксисах. `endpoint-
33
+ # declarations` переехал по той же причине с другого конца: маршрут оказался не
34
+ # единственным входом в процесс, а второй вид входа в плоскую секцию не встаёт.
35
+ RETIRED: Final[dict[str, Moved]] = {
36
+ "class-modules": Moved(
37
+ into="layout",
38
+ written="`only`",
39
+ ),
40
+ "class-placement": Moved(
41
+ into="layout",
42
+ written="`home` и `suffix`",
43
+ ),
44
+ "required-class": Moved(
45
+ into="layout",
46
+ written="`required` рядом с `suffix`",
47
+ ),
48
+ "operation-shape": Moved(
49
+ into="layout",
50
+ written="`operation`",
51
+ ),
52
+ "model-boundary": Moved(
53
+ into="layout",
54
+ written="`orm` и `base`",
55
+ ),
56
+ "endpoint-declarations": Moved(
57
+ into="edge-declarations",
58
+ written="блок вида входа — `route` с теми же ключами",
59
+ ),
29
60
  }
30
61
 
31
62
 
@@ -34,15 +65,18 @@ def retired(
34
65
  checks: Mapping[str, object],
35
66
  source: Path | None,
36
67
  ) -> None:
37
- """Падает, если в настройках остались секции, которые слились в `[layout]`."""
38
- found = [name for name in RETIRED if name in checks]
68
+ """Падает, если в настройках остались секции, которые слились в общие таблицы."""
69
+ found = sorted(name for name in RETIRED if name in checks)
39
70
  if not found:
40
71
  return
41
72
  named = prefix(source=source)
42
- listed = ", ".join(f"[{named}{name}] -> {RETIRED[name]}" for name in sorted(found))
73
+ listed = "; ".join(
74
+ f"[{named}{name}] -> [{named}{RETIRED[name].into}], {RETIRED[name].written}"
75
+ for name in found
76
+ )
43
77
  raise ConfigError(
44
- f"эти секции слились в общую таблицу [{named}layout], блок на директорию: "
45
- f"{listed}. Одна директория — один блок, а не четыре строки в четырёх таблицах"
78
+ f"эти секции больше не читаются, их содержимое переехало в общие таблицы, "
79
+ f"блок на предмет разговора: {listed}"
46
80
  )
47
81
 
48
82
 
@@ -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
 
@@ -4,8 +4,8 @@ py_checks/checks/_kind.py,sha256=VS0N2fBYC3iJcF-5OUAlGtTcvYeUtAmQGyF5VjyDULc,668
4
4
  py_checks/checks/_layout.py,sha256=qBOp44cVexG50nTE5SBEfFAsVJfzXh5Q-0RsVH4GdUg,11024
5
5
  py_checks/checks/_location.py,sha256=VW6wkqWsCYDUwn2DOvYgbM5YYaxw1V537nKj6HFt4vk,5299
6
6
  py_checks/checks/_names.py,sha256=C5ECC9jMe0vvxzC-_B5iq5WmOJXvY_k9v8vpTliYDaQ,3853
7
- py_checks/checks/api/__init__.py,sha256=Frr1DFxkK-byptVPNnhp-im5o2IJwWN7pxVoOW51jsk,492
8
- py_checks/checks/api/_endpoint_declarations.py,sha256=Qo7JVB14zREgOO0WGrlJbBoL8jSIDLsE0eLDPJbZsJI,8281
7
+ py_checks/checks/api/__init__.py,sha256=UOTwKhn7jwNG0Fbj2xQCh44QFloegzJtiSF-OxIKDmo,627
8
+ py_checks/checks/api/_edge_declarations.py,sha256=8ktmMPzRBj_tG1gUxdfcJvq_-LEeFwemYTvIh3dmDMU,15296
9
9
  py_checks/checks/api/_marker.py,sha256=u--5bRpiSiZoYomuMsJF96jVykKmz5XkjbFBmwrOw1I,147
10
10
  py_checks/checks/calls/__init__.py,sha256=pbWinB9SFxryxhR6MCwizc4csdp4ALELgj4lOHUdEvY,522
11
11
  py_checks/checks/calls/_confined_functions.py,sha256=5zmbnbx8a03VvFTJ_DiVlK_333T2NJ8KBHjJAia8Sos,3798
@@ -23,6 +23,9 @@ py_checks/checks/effects/__init__.py,sha256=RSTWX92fEQKtksEQMmNLgS-XRkMm-uAm9box
23
23
  py_checks/checks/effects/_determinism.py,sha256=wy5L-MvUTg0QuSAufLwkIvSr1_nQK8i2LuxEA7uYNv0,4200
24
24
  py_checks/checks/effects/_log_events.py,sha256=mMzgul8IYoQJXaSLFzH80bhQMAkn3HHCexEu3FTlUic,4580
25
25
  py_checks/checks/effects/_marker.py,sha256=MiLJbi9XgR-IQCeyEYdZZcN84i-FfA2PNe3AtNvY9Zo,153
26
+ py_checks/checks/errors/__init__.py,sha256=HrsWLgkzulRpJthC3JYsfKL-thz_aaTbxvvIw5CB998,382
27
+ py_checks/checks/errors/_marker.py,sha256=QY9PSIwAswTZhbAfxesvLS6aT2RPUBqnbjMwCsEQduc,151
28
+ py_checks/checks/errors/_refusals.py,sha256=6dPlAG2RlB233H6neHV3ms2_CTtCVshsFaLNpjQVSUM,6974
26
29
  py_checks/checks/hygiene/__init__.py,sha256=jgKnJdJUPD8mpxCwDKLwup9K-U4nYPxYxaMTSRCUeFM,655
27
30
  py_checks/checks/hygiene/_dependency_bounds.py,sha256=SZtpbk0zINirXsexEMvRNW-FyjsCkzt3YUkloN9_XOA,8208
28
31
  py_checks/checks/hygiene/_marker.py,sha256=RkKZqmsvwIPxhsIe4GBFt85CmThVLZhWp6Hyw2EXHcM,155
@@ -64,7 +67,7 @@ py_checks/cli/commands/_summary.py,sha256=wh02ERo0sSq-D6xLS2CBcNMTvXieAPOZz2Qsau
64
67
  py_checks/cli/commands/_sync.py,sha256=KraoBgF-n8wj2NFjLl9EsSEIk-Ijpfi-yQNijHrCQdg,2317
65
68
  py_checks/config/__init__.py,sha256=oaKdKexHXCEAgQULhS2WVgRNyji68cjDx1QLjWgb5Kk,1225
66
69
  py_checks/config/_base.py,sha256=Id6VdFdAL6E4RRQx3PK5fJ19EsRPFvkUbKeZmBAhak0,1530
67
- py_checks/config/_config.py,sha256=3qr13MjRmwmVd9mgLJl4dv9VvMyGUB_hyGTIAoSi4l0,4910
70
+ py_checks/config/_config.py,sha256=6wCBJ2EIlL5P8TTKBgiRZyaCUNDXqM_OSXV6muXmxCE,5889
68
71
  py_checks/config/_constants.py,sha256=vOBWDbooOBxiLat9oQ9dj3E4xEmWE-kQGfn9cwpWl64,1206
69
72
  py_checks/config/_errors.py,sha256=l4k1ZZzfQjHfhqp8erlvBNAV3A3nNFN2v52dt30PAVY,547
70
73
  py_checks/config/_loader.py,sha256=iPtxth7MB3IYKoBEv4RlJmQNlH_fkFhtqtRltS9df-U,5229
@@ -97,8 +100,8 @@ py_checks/environment/_settings.py,sha256=Pr0xE05tt7iagffzK11NncTN22QeoZKtxA2zuC
97
100
  py_checks/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
98
101
  py_checks/sync/__init__.py,sha256=Kg08BC7arCTqdFk2tO3qm95_jG-X0vxK-GMvVYJEkXc,1041
99
102
  py_checks/sync/_sync.py,sha256=KqA65H4zeP6y17LwlRR8svpCuhUdFCY3KIwG3YtuvAk,2254
100
- python_checks-0.4.2.dist-info/licenses/LICENSE,sha256=omcAXq_cAQNMI5X3fRdH7UC6W2Zc8AC-G9xIZ2U1xF0,1065
101
- python_checks-0.4.2.dist-info/WHEEL,sha256=R1d3uUTbmXM1FHXH_itQashbrqrOSVj-hvBCpmkIIGE,81
102
- python_checks-0.4.2.dist-info/entry_points.txt,sha256=59rS_KMwYdFnQ9HuhkBpKQNKySNAALyneIFO_-cVQvw,1679
103
- python_checks-0.4.2.dist-info/METADATA,sha256=pYhI5fJOs2hav1TY5aBy8XJV1THKrMMNiMBHsO1Mmvc,15389
104
- python_checks-0.4.2.dist-info/RECORD,,
103
+ python_checks-0.5.0.dist-info/licenses/LICENSE,sha256=omcAXq_cAQNMI5X3fRdH7UC6W2Zc8AC-G9xIZ2U1xF0,1065
104
+ python_checks-0.5.0.dist-info/WHEEL,sha256=R1d3uUTbmXM1FHXH_itQashbrqrOSVj-hvBCpmkIIGE,81
105
+ python_checks-0.5.0.dist-info/entry_points.txt,sha256=TtWmUfXcevBejdpwhas4_nNHwVEOW4Qleq2OgafxwbE,1715
106
+ python_checks-0.5.0.dist-info/METADATA,sha256=HCWG9Z_4eaiZFnAOvQ73ahY4iDOHmXAQimcESrVbXCY,15459
107
+ python_checks-0.5.0.dist-info/RECORD,,
@@ -14,7 +14,7 @@ confined-types = py_checks.checks.types:ConfinedTypes
14
14
  constant-annotations = py_checks.checks.types:ConstantAnnotations
15
15
  dependency-bounds = py_checks.checks.hygiene:DependencyBounds
16
16
  determinism = py_checks.checks.effects:Determinism
17
- endpoint-declarations = py_checks.checks.api:EndpointDeclarations
17
+ edge-declarations = py_checks.checks.api:EdgeDeclarations
18
18
  frozen-dataclasses = py_checks.checks.types:FrozenDataclasses
19
19
  function-length = py_checks.checks.signatures:FunctionLength
20
20
  keyword-only-arguments = py_checks.checks.signatures:KeywordOnlyArguments
@@ -25,6 +25,7 @@ module-length = py_checks.checks.signatures:ModuleLength
25
25
  nesting = py_checks.checks.signatures:Nesting
26
26
  operation-shape = py_checks.checks.placement:OperationShape
27
27
  raw-sql = py_checks.checks.database:RawSql
28
+ refusals = py_checks.checks.errors:Refusals
28
29
  required-class = py_checks.checks.placement:RequiredClass
29
30
  schema-drift = py_checks.checks.database:SchemaDrift
30
31
  sealed-imports = py_checks.checks.imports:SealedImports
@@ -1,204 +0,0 @@
1
- """Маршрут объявляет в декораторе всё, чем он будет описан в схеме."""
2
-
3
- from __future__ import annotations
4
-
5
- import ast
6
- from http import HTTPStatus
7
- from typing import TYPE_CHECKING, ClassVar, Final
8
-
9
- from py_checks.checks.api._marker import MARKER
10
- from py_checks.config import CheckSettings
11
- from py_checks.core import Scope, Violation, settings_as
12
-
13
- if TYPE_CHECKING:
14
- from collections.abc import Iterator
15
-
16
- from py_checks.core import ParsedFile
17
-
18
- CODE: Final = "endpoint-declarations"
19
-
20
- PATH: Final = "path"
21
- STATUS: Final = "status_code"
22
-
23
-
24
- class EndpointDeclarationsSettings(CheckSettings):
25
- methods: tuple[str, ...] = ()
26
- required: tuple[str, ...] = ()
27
- body: str | None = None
28
- bodiless: tuple[int, ...] = ()
29
- exempt: str | None = None
30
-
31
-
32
- class EndpointDeclarations:
33
- """Падает, если маршрут не сказал, чем он отвечает.
34
-
35
- Декоратор маршрута — это контракт. Кто читает сгенерированную схему —
36
- соседний сервис, человек, пишущий клиент, — читает только то, что объявил
37
- декоратор, и поле, которого там нет, для него не существует, что бы ни
38
- возвращало тело функции.
39
-
40
- Механизм у фреймворка есть, требования писать — нет. Маршрут без `summary`
41
- попадёт в схему с именем функции вместо описания, а с пустым `responses` —
42
- с обещанием, что отказов у него не бывает: успех из подписи выводится,
43
- отказы — нет, и ничто в ней не говорит, что этот маршрут отвечает 409.
44
-
45
- Путь пишется словом `path=`: позиционный первый аргумент — единственное в
46
- декораторе, чей смысл зависит от позиции.
47
-
48
- Тело объявляется отдельно от прочего и не требуется там, где его не
49
- бывает: 204, 205 и 304 — это статусы без тела, и модель ответа рядом с
50
- ними обещает то, что протокол запрещает. Статус, записанный не числом и не
51
- членом `HTTPStatus`, читается как неизвестный, а неизвестный считается
52
- имеющим тело: проверка, сработавшая зря, снимается пометкой, а
53
- промолчавшая — это контракт, которого никто не хватится.
54
-
55
- Маршрут, выведенный из схемы (`include_in_schema=False`), правило не
56
- трогает: схема — это то, что оно защищает, а такого маршрута в ней нет.
57
-
58
- Настройки: `methods`, `required`, `body`, `bodiless`, `exempt`.
59
- """
60
-
61
- code: ClassVar[str] = CODE
62
- Settings: ClassVar[type[CheckSettings]] = EndpointDeclarationsSettings
63
- scope: ClassVar[Scope] = Scope.FILE
64
- marker: ClassVar[str] = MARKER
65
-
66
- @classmethod
67
- def run(
68
- cls,
69
- *,
70
- file: ParsedFile,
71
- settings: CheckSettings,
72
- ) -> Iterator[Violation]:
73
- limits = settings_as(
74
- settings=settings,
75
- model=EndpointDeclarationsSettings,
76
- code=CODE,
77
- )
78
- if not limits.methods:
79
- return
80
- for node in ast.walk(file.tree):
81
- if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
82
- continue
83
- for decorator in node.decorator_list:
84
- if not isinstance(decorator, ast.Call):
85
- continue
86
- if not cls._route(
87
- node=decorator,
88
- methods=limits.methods,
89
- ):
90
- continue
91
- yield from cls._judged(
92
- route=decorator,
93
- file=file,
94
- limits=limits,
95
- )
96
-
97
- @classmethod
98
- def _judged(
99
- cls,
100
- *,
101
- route: ast.Call,
102
- file: ParsedFile,
103
- limits: EndpointDeclarationsSettings,
104
- ) -> Iterator[Violation]:
105
- if cls._unpublished(
106
- route=route,
107
- exempt=limits.exempt,
108
- ):
109
- return
110
- named = cls._name(route=route)
111
- declared = {keyword.arg for keyword in route.keywords}
112
- if route.args:
113
- yield cls._violation(
114
- route=route,
115
- file=file,
116
- message=f"{named} передаёт путь позиционно; напиши {PATH}=",
117
- )
118
- for wanted in limits.required:
119
- if wanted in declared or (wanted == PATH and route.args):
120
- continue
121
- yield cls._violation(
122
- route=route,
123
- file=file,
124
- message=f"{named} не объявляет {wanted}=",
125
- )
126
- if limits.body is None or limits.body in declared:
127
- return
128
- if cls._status(route=route) in limits.bodiless:
129
- return
130
- yield cls._violation(
131
- route=route,
132
- file=file,
133
- message=(
134
- f"{named} не объявляет {limits.body}= и отвечает телом; "
135
- f"без него отвечают {', '.join(str(status) for status in limits.bodiless)}"
136
- ),
137
- )
138
-
139
- @staticmethod
140
- def _violation(
141
- *,
142
- route: ast.Call,
143
- file: ParsedFile,
144
- message: str,
145
- ) -> Violation:
146
- return Violation.from_node(
147
- node=route,
148
- path=file.path,
149
- code=CODE,
150
- message=message,
151
- )
152
-
153
- @staticmethod
154
- def _route(
155
- *,
156
- node: ast.Call,
157
- methods: tuple[str, ...],
158
- ) -> bool:
159
- """Декоратор вида `<что-то>.<метод>(...)`, а не `@app.middleware(...)`."""
160
- return isinstance(node.func, ast.Attribute) and node.func.attr in methods
161
-
162
- @staticmethod
163
- def _unpublished(
164
- *,
165
- route: ast.Call,
166
- exempt: str | None,
167
- ) -> bool:
168
- """Маршрут сказал, что в схеме его нет."""
169
- return exempt is not None and any(
170
- keyword.arg == exempt
171
- and isinstance(keyword.value, ast.Constant)
172
- and keyword.value.value is False
173
- for keyword in route.keywords
174
- )
175
-
176
- @staticmethod
177
- def _name(*, route: ast.Call) -> str:
178
- """`POST '/tickets'` — как бы путь ни был записан.
179
-
180
- Путь читается и из слова, и из первого аргумента: сообщение обязано
181
- назвать маршрут и в том файле, где слова как раз нет, — «GET не
182
- объявляет summary» в модуле с шестью GET не называет ничего.
183
- """
184
- attribute = route.func
185
- method = attribute.attr.upper() if isinstance(attribute, ast.Attribute) else ""
186
- written = [keyword.value for keyword in route.keywords if keyword.arg == PATH]
187
- path = route.args[:1] + written
188
- return f"{method} {ast.unparse(path[0])}" if path else method
189
-
190
- @staticmethod
191
- def _status(*, route: ast.Call) -> int | None:
192
- """Статус, если он записан так, что его видно по файлу."""
193
- for keyword in route.keywords:
194
- if keyword.arg != STATUS:
195
- continue
196
- match keyword.value:
197
- case ast.Constant(value=int() as status):
198
- return status
199
- case ast.Attribute(value=ast.Name(id="HTTPStatus"), attr=name):
200
- found = getattr(HTTPStatus, name, None)
201
- return None if found is None else int(found)
202
- case _:
203
- return None
204
- return None