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.
- py_checks/checks/__init__.py +15 -14
- py_checks/checks/_kind.py +34 -32
- py_checks/checks/_layout.py +75 -68
- py_checks/checks/_location.py +53 -31
- py_checks/checks/_names.py +25 -23
- py_checks/checks/api/__init__.py +12 -7
- py_checks/checks/api/_edge_declarations.py +388 -0
- py_checks/checks/api/_marker.py +1 -1
- py_checks/checks/calls/__init__.py +3 -3
- py_checks/checks/calls/_confined_functions.py +15 -14
- py_checks/checks/calls/_marker.py +1 -1
- py_checks/checks/database/__init__.py +7 -5
- py_checks/checks/database/_bound_checks.py +32 -31
- py_checks/checks/database/_confined_calls.py +23 -23
- py_checks/checks/database/_marker.py +1 -1
- py_checks/checks/database/_model_boundary.py +37 -36
- py_checks/checks/database/_model_columns.py +36 -36
- py_checks/checks/database/_raw_sql.py +40 -37
- py_checks/checks/database/_schema_drift.py +50 -47
- py_checks/checks/database/_statement_keys.py +29 -28
- py_checks/checks/effects/__init__.py +6 -5
- py_checks/checks/effects/_determinism.py +26 -23
- py_checks/checks/effects/_log_events.py +18 -18
- py_checks/checks/effects/_marker.py +1 -1
- py_checks/checks/errors/__init__.py +10 -0
- py_checks/checks/errors/_marker.py +5 -0
- py_checks/checks/errors/_refusals.py +160 -0
- py_checks/checks/hygiene/__init__.py +5 -4
- py_checks/checks/hygiene/_dependency_bounds.py +33 -33
- py_checks/checks/hygiene/_marker.py +1 -1
- py_checks/checks/imports/__init__.py +9 -9
- py_checks/checks/imports/_confined.py +15 -14
- py_checks/checks/imports/_marker.py +1 -1
- py_checks/checks/imports/_sealed.py +17 -28
- py_checks/checks/imports/_statements.py +5 -5
- py_checks/checks/placement/__init__.py +11 -11
- py_checks/checks/placement/_class_modules.py +17 -15
- py_checks/checks/placement/_class_placement.py +16 -15
- py_checks/checks/placement/_marker.py +1 -1
- py_checks/checks/placement/_operation_shape.py +56 -54
- py_checks/checks/placement/_required_class.py +28 -28
- py_checks/checks/signatures/__init__.py +6 -5
- py_checks/checks/signatures/_function_length.py +18 -17
- py_checks/checks/signatures/_functions.py +13 -12
- py_checks/checks/signatures/_keyword_only.py +23 -21
- py_checks/checks/signatures/_marker.py +1 -1
- py_checks/checks/signatures/_module_length.py +8 -8
- py_checks/checks/signatures/_nesting.py +20 -20
- py_checks/checks/signatures/_signature_layout.py +46 -47
- py_checks/checks/types/__init__.py +5 -4
- py_checks/checks/types/_annotation_shapes.py +20 -20
- py_checks/checks/types/_config_fields.py +44 -43
- py_checks/checks/types/_confined_types.py +26 -26
- py_checks/checks/types/_constant_annotations.py +18 -17
- py_checks/checks/types/_frozen_dataclasses.py +14 -13
- py_checks/checks/types/_marker.py +1 -1
- py_checks/cli/__init__.py +3 -3
- py_checks/cli/_app.py +3 -3
- py_checks/cli/_protocols.py +6 -5
- py_checks/cli/commands/__init__.py +6 -4
- py_checks/cli/commands/_doctor.py +81 -67
- py_checks/cli/commands/_explain.py +15 -14
- py_checks/cli/commands/_list.py +10 -10
- py_checks/cli/commands/_mutation.py +247 -0
- py_checks/cli/commands/_run.py +25 -26
- py_checks/cli/commands/_summary.py +3 -3
- py_checks/cli/commands/_sync.py +9 -9
- py_checks/config/__init__.py +7 -7
- py_checks/config/_base.py +11 -10
- py_checks/config/_config.py +68 -31
- py_checks/config/_constants.py +7 -7
- py_checks/config/_errors.py +5 -5
- py_checks/config/_loader.py +22 -21
- py_checks/config/_toml.py +5 -4
- py_checks/contracts/__init__.py +9 -9
- py_checks/contracts/_constants.py +4 -4
- py_checks/contracts/_layout.py +7 -6
- py_checks/contracts/_render.py +26 -25
- py_checks/contracts/_settings.py +11 -11
- py_checks/core/__init__.py +4 -4
- py_checks/core/_constants.py +7 -6
- py_checks/core/_discovery.py +6 -6
- py_checks/core/_edit.py +18 -15
- py_checks/core/_errors.py +4 -4
- py_checks/core/_fixer.py +5 -5
- py_checks/core/_format.py +7 -7
- py_checks/core/_markers.py +41 -37
- py_checks/core/_paths.py +14 -12
- py_checks/core/_protocols.py +33 -29
- py_checks/core/_registry.py +15 -13
- py_checks/core/_report.py +8 -7
- py_checks/core/_runner.py +18 -18
- py_checks/core/_settings.py +8 -8
- py_checks/core/_source.py +14 -13
- py_checks/core/_violation.py +15 -13
- py_checks/environment/__init__.py +6 -6
- py_checks/environment/_constants.py +1 -1
- py_checks/environment/_render.py +38 -37
- py_checks/environment/_settings.py +11 -10
- py_checks/mutation/__init__.py +34 -0
- py_checks/mutation/_baseline.py +47 -0
- py_checks/mutation/_constants.py +11 -0
- py_checks/mutation/_errors.py +12 -0
- py_checks/mutation/_gate.py +175 -0
- py_checks/mutation/_mutmut.py +162 -0
- py_checks/mutation/_process.py +44 -0
- py_checks/mutation/_scope.py +155 -0
- py_checks/mutation/_settings.py +54 -0
- py_checks/sync/__init__.py +9 -9
- py_checks/sync/_sync.py +11 -10
- {python_checks-0.4.2.dist-info → python_checks-0.6.0.dist-info}/METADATA +9 -4
- python_checks-0.6.0.dist-info/RECORD +117 -0
- {python_checks-0.4.2.dist-info → python_checks-0.6.0.dist-info}/WHEEL +1 -1
- {python_checks-0.4.2.dist-info → python_checks-0.6.0.dist-info}/entry_points.txt +2 -1
- py_checks/checks/api/_endpoint_declarations.py +0 -204
- python_checks-0.4.2.dist-info/RECORD +0 -104
- {python_checks-0.4.2.dist-info → python_checks-0.6.0.dist-info}/licenses/LICENSE +0 -0
py_checks/checks/_names.py
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""Names: how they are read in the tree and matched against the settings.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
`mapped_column
|
|
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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
|
|
40
|
-
|
|
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]`
|
|
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
|
-
"""
|
|
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)
|
py_checks/checks/api/__init__.py
CHANGED
|
@@ -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.
|
|
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,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
|
py_checks/checks/api/_marker.py
CHANGED
|
@@ -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
|
-
|
|
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}()
|
|
84
|
+
message=f"{called}() is not called from here; its places are {', '.join(allowed)}",
|
|
84
85
|
)
|
|
85
86
|
|
|
86
87
|
@staticmethod
|
|
@@ -1,9 +1,11 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""The database.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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
|