python-checks 0.4.1__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.
- py_checks/checks/_layout.py +21 -1
- py_checks/checks/api/__init__.py +11 -6
- py_checks/checks/api/_edge_declarations.py +381 -0
- py_checks/checks/errors/__init__.py +10 -0
- py_checks/checks/errors/_marker.py +5 -0
- py_checks/checks/errors/_refusals.py +159 -0
- py_checks/checks/placement/_class_placement.py +6 -1
- py_checks/config/_config.py +49 -15
- {python_checks-0.4.1.dist-info → python_checks-0.5.0.dist-info}/METADATA +6 -4
- {python_checks-0.4.1.dist-info → python_checks-0.5.0.dist-info}/RECORD +13 -10
- {python_checks-0.4.1.dist-info → python_checks-0.5.0.dist-info}/entry_points.txt +2 -1
- py_checks/checks/api/_endpoint_declarations.py +0 -204
- {python_checks-0.4.1.dist-info → python_checks-0.5.0.dist-info}/WHEEL +0 -0
- {python_checks-0.4.1.dist-info → python_checks-0.5.0.dist-info}/licenses/LICENSE +0 -0
py_checks/checks/_layout.py
CHANGED
|
@@ -90,6 +90,9 @@ class Directory(CheckSettings):
|
|
|
90
90
|
`only` — виды, которым здесь место, и ничего другого рядом не садится.
|
|
91
91
|
`home` — виды, которым место ТОЛЬКО здесь: порт, объявленный в другом
|
|
92
92
|
конце дерева, — это порт, которого читатель не найдёт.
|
|
93
|
+
`area` — часть дерева, внутри которой дом и имя вообще о чём-то говорят:
|
|
94
|
+
правило про `dto` написано про слой приложения, а dataclass в загрузчике
|
|
95
|
+
или в наблюдаемости — просто способ сложить три поля рядом.
|
|
93
96
|
`suffix` — как зовут класс, ради которого директория существует; он же
|
|
94
97
|
живёт только здесь.
|
|
95
98
|
`required` — модуль обязан объявить такой класс, первым и один.
|
|
@@ -100,6 +103,7 @@ class Directory(CheckSettings):
|
|
|
100
103
|
|
|
101
104
|
only: tuple[Kind, ...] = ()
|
|
102
105
|
home: tuple[Kind, ...] = ()
|
|
106
|
+
area: str | None = None
|
|
103
107
|
suffix: str | None = None
|
|
104
108
|
required: bool = False
|
|
105
109
|
operation: Operation | None = None
|
|
@@ -119,6 +123,14 @@ class Directory(CheckSettings):
|
|
|
119
123
|
raise ValueError(message)
|
|
120
124
|
return self
|
|
121
125
|
|
|
126
|
+
@model_validator(mode="after")
|
|
127
|
+
def _claims(self) -> Self:
|
|
128
|
+
"""Область сужает притязание: без дома и имени сужать нечего."""
|
|
129
|
+
if self.area is not None and not self.home and self.suffix is None:
|
|
130
|
+
message = "`area` без `home` и `suffix`: эта директория ни на что не притязает"
|
|
131
|
+
raise ValueError(message)
|
|
132
|
+
return self
|
|
133
|
+
|
|
122
134
|
@model_validator(mode="after")
|
|
123
135
|
def _declares(self) -> Self:
|
|
124
136
|
"""`base` — про дом моделей: в месте сборки узнавать по базе нечего."""
|
|
@@ -188,10 +200,18 @@ def claimants(
|
|
|
188
200
|
*,
|
|
189
201
|
declared: Declaration,
|
|
190
202
|
layout: dict[str, Directory],
|
|
203
|
+
where: Place,
|
|
191
204
|
) -> list[Claim]:
|
|
192
|
-
"""Адреса, объявившие это объявление своим: по имени или по виду.
|
|
205
|
+
"""Адреса, объявившие это объявление своим: по имени или по виду.
|
|
206
|
+
|
|
207
|
+
Блок с `area` притязает только на то, что лежит внутри названной части
|
|
208
|
+
дерева: соглашение про `dto` написано про слой приложения, и dataclass в
|
|
209
|
+
загрузчике ему не подсуден.
|
|
210
|
+
"""
|
|
193
211
|
found: list[Claim] = []
|
|
194
212
|
for address, directory in layout.items():
|
|
213
|
+
if directory.area is not None and not where.holds(path=directory.area):
|
|
214
|
+
continue
|
|
195
215
|
said = _claim(
|
|
196
216
|
declared=declared,
|
|
197
217
|
directory=directory,
|
py_checks/checks/api/__init__.py
CHANGED
|
@@ -1,13 +1,18 @@
|
|
|
1
1
|
"""API и события.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
фреймворка есть, требования писать —
|
|
3
|
+
Вход в процесс объявляет в декораторе всё, что за него решили: механизм у
|
|
4
|
+
фреймворка есть, требования писать — нет, а каждое его умолчание — решение,
|
|
5
|
+
принятое не этим проектом.
|
|
5
6
|
"""
|
|
6
7
|
|
|
7
|
-
from py_checks.checks.api.
|
|
8
|
-
|
|
9
|
-
|
|
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", "
|
|
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,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
|
+
)
|
|
@@ -32,7 +32,11 @@ class ClassPlacement:
|
|
|
32
32
|
`dataclass` не назвал своего дома, он лежит где угодно. Назвал — значит
|
|
33
33
|
перечислены все дома, в том числе доменный: value object тоже dataclass.
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
`area` сужает притязание до части дерева: соглашение про `dto` написано
|
|
36
|
+
про слой приложения, а dataclass в загрузчике или в наблюдаемости — это
|
|
37
|
+
способ сложить три поля рядом, а не предмет разговора.
|
|
38
|
+
|
|
39
|
+
Настройки: `home`, `suffix` и `area` в общей таблице `[layout]`.
|
|
36
40
|
"""
|
|
37
41
|
|
|
38
42
|
code: ClassVar[str] = CODE
|
|
@@ -60,6 +64,7 @@ class ClassPlacement:
|
|
|
60
64
|
homes = claimants(
|
|
61
65
|
declared=declared,
|
|
62
66
|
layout=layout,
|
|
67
|
+
where=where,
|
|
63
68
|
)
|
|
64
69
|
if not homes or any(where.holds(path=home.address) for home in homes):
|
|
65
70
|
continue
|
py_checks/config/_config.py
CHANGED
|
@@ -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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
"""Падает, если в настройках остались секции, которые слились в
|
|
38
|
-
found =
|
|
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 = "
|
|
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"эти секции
|
|
45
|
-
f"
|
|
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.
|
|
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:
|
|
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
|
|
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
|
-
| `
|
|
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
|
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
py_checks/__init__.py,sha256=xR8QJ9loLxCkxktQedfgoesRfCP8eQMAeijGbZVDE70,55
|
|
2
2
|
py_checks/checks/__init__.py,sha256=x6A8C2GMqDw8JrfYP9kAezVhU7njlR6GHX86Iz62Bok,1596
|
|
3
3
|
py_checks/checks/_kind.py,sha256=VS0N2fBYC3iJcF-5OUAlGtTcvYeUtAmQGyF5VjyDULc,6681
|
|
4
|
-
py_checks/checks/_layout.py,sha256=
|
|
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=
|
|
8
|
-
py_checks/checks/api/
|
|
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
|
|
@@ -33,7 +36,7 @@ py_checks/checks/imports/_sealed.py,sha256=9slBw8MrBpn3h211qd8sgVWuq_Yvkq-h0Iyww
|
|
|
33
36
|
py_checks/checks/imports/_statements.py,sha256=tIioHIV9Hi3v2XEzG2LT2YUKhDKQBQd8VWd2W-uNqEs,1633
|
|
34
37
|
py_checks/checks/placement/__init__.py,sha256=shA9CrcQ_1CeHxzRooCIECFEMWA2h7dmxTO2TpS1WZc,1908
|
|
35
38
|
py_checks/checks/placement/_class_modules.py,sha256=ddUf9ou7pD_rE0ArXo-MYP-G0s63mf3GnvXYu2NAdbk,3516
|
|
36
|
-
py_checks/checks/placement/_class_placement.py,sha256=
|
|
39
|
+
py_checks/checks/placement/_class_placement.py,sha256=ld_7b_e7ALj7bEY0fqjnjM_YVTGSq81t7jEckUGLH-o,3378
|
|
37
40
|
py_checks/checks/placement/_marker.py,sha256=4doJFqqtYAo5m7Tm2MWU4WbTccjiAuvzoPEbwwwWEGQ,199
|
|
38
41
|
py_checks/checks/placement/_operation_shape.py,sha256=B6Cw04_kiS1DlZCKPxANONpUp_iduYEP-z66YoaUhyM,14831
|
|
39
42
|
py_checks/checks/placement/_required_class.py,sha256=h6t-DWt3fiTNTADXUvZbkxBffynxmixNFugjYhTLjaQ,6620
|
|
@@ -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=
|
|
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.
|
|
101
|
-
python_checks-0.
|
|
102
|
-
python_checks-0.
|
|
103
|
-
python_checks-0.
|
|
104
|
-
python_checks-0.
|
|
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
|
-
|
|
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
|
|
File without changes
|
|
File without changes
|