python-checks 0.5.0__py3-none-any.whl → 0.7.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 +100 -72
- py_checks/checks/_location.py +73 -31
- py_checks/checks/_names.py +25 -23
- py_checks/checks/api/__init__.py +4 -4
- py_checks/checks/api/_edge_declarations.py +80 -73
- 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 +3 -3
- py_checks/checks/errors/_marker.py +1 -1
- py_checks/checks/errors/_refusals.py +39 -38
- 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 +32 -20
- py_checks/checks/placement/_class_placement.py +19 -17
- py_checks/checks/placement/_marker.py +1 -1
- py_checks/checks/placement/_operation_shape.py +140 -77
- py_checks/checks/placement/_required_class.py +77 -34
- 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 +104 -68
- 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 +33 -30
- 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 +7 -4
- py_checks/contracts/_layout.py +7 -6
- py_checks/contracts/_render.py +80 -31
- py_checks/contracts/_settings.py +13 -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.5.0.dist-info → python_checks-0.7.0.dist-info}/METADATA +4 -1
- python_checks-0.7.0.dist-info/RECORD +117 -0
- {python_checks-0.5.0.dist-info → python_checks-0.7.0.dist-info}/WHEEL +1 -1
- python_checks-0.5.0.dist-info/RECORD +0 -107
- {python_checks-0.5.0.dist-info → python_checks-0.7.0.dist-info}/entry_points.txt +0 -0
- {python_checks-0.5.0.dist-info → python_checks-0.7.0.dist-info}/licenses/LICENSE +0 -0
py_checks/checks/__init__.py
CHANGED
|
@@ -1,20 +1,21 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""The rule implementations, one package per group.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Inside a group, one module per check. Rules that moved to import-linter, ruff
|
|
4
|
+
and alembic are not carried over here; what went where is written down in
|
|
5
5
|
`docs/current.md`.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
`@staticmethod
|
|
10
|
-
|
|
7
|
+
A check is one class, and everything it reads the tree with lives inside it:
|
|
8
|
+
helpers do not spread across the module, and it is clear whose they are. A
|
|
9
|
+
leaf takes `@staticmethod`; a helper that calls another helper takes
|
|
10
|
+
`@classmethod`, so it calls through `cls` rather than by the class's name.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
`_location.py`,
|
|
15
|
-
|
|
12
|
+
Inside the class lives what belongs to the rule. A word of the language does
|
|
13
|
+
not belong to a rule: "what is this node called" is `_names.py`, "where does
|
|
14
|
+
this file lie" is `_location.py`, "what is declared here" is `_kind.py`. Six
|
|
15
|
+
identical `_name` across classes are not six helpers but one, forgotten in six
|
|
16
|
+
places.
|
|
16
17
|
|
|
17
|
-
|
|
18
|
-
`_marker.py
|
|
19
|
-
|
|
18
|
+
The word that lifts a rule from the code is declared once per group, in the
|
|
19
|
+
package's `_marker.py`. It lifts any check of the group; to lift exactly one,
|
|
20
|
+
there is `# check-ok: <code>: <reason>`.
|
|
20
21
|
"""
|
py_checks/checks/_kind.py
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""What a module declares: a class, a port, a dataclass, an alias.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
The placement rules speak of kinds of declaration, not of syntax: "`dto/` holds
|
|
4
|
+
dataclasses", "`ports/` holds protocols". The kind is recognised once, here,
|
|
5
|
+
and every rule of the group uses the same knowledge.
|
|
6
6
|
"""
|
|
7
7
|
|
|
8
8
|
from __future__ import annotations
|
|
@@ -27,12 +27,12 @@ ENUMS: Final[frozenset[str]] = frozenset(
|
|
|
27
27
|
|
|
28
28
|
ERROR_BASES: Final[frozenset[str]] = frozenset({"Exception", "BaseException"})
|
|
29
29
|
|
|
30
|
-
#
|
|
31
|
-
#
|
|
32
|
-
#
|
|
30
|
+
# A project's exception inherits from its own root (`class NotFound(DomainError)`),
|
|
31
|
+
# not from `Exception` — but the root's name ends the same way, and the kind is
|
|
32
|
+
# recognised by it without reading another module.
|
|
33
33
|
ERROR_SUFFIXES: Final[tuple[str, ...]] = ("Error", "Exception")
|
|
34
34
|
|
|
35
|
-
#
|
|
35
|
+
# An assignment that declares a name for a type, not a value.
|
|
36
36
|
ALIAS_ANNOTATION: Final = "TypeAlias"
|
|
37
37
|
ALIAS_FACTORIES: Final[frozenset[str]] = frozenset(
|
|
38
38
|
{"TypeVar", "NewType", "ParamSpec", "TypeAliasType"},
|
|
@@ -54,7 +54,7 @@ ALIAS_CONSTRUCTORS: Final[frozenset[str]] = frozenset(
|
|
|
54
54
|
|
|
55
55
|
|
|
56
56
|
class Kind(StrEnum):
|
|
57
|
-
"""
|
|
57
|
+
"""The kinds of declaration the placement rules speak of."""
|
|
58
58
|
|
|
59
59
|
CLASS = "class"
|
|
60
60
|
PORT = "port"
|
|
@@ -67,29 +67,29 @@ class Kind(StrEnum):
|
|
|
67
67
|
|
|
68
68
|
@property
|
|
69
69
|
def said(self) -> str:
|
|
70
|
-
"""
|
|
70
|
+
"""What the kind is called in a message: `str.title` is taken by `str` itself."""
|
|
71
71
|
return NAMES[self]
|
|
72
72
|
|
|
73
73
|
|
|
74
74
|
NAMES: Final[dict[Kind, str]] = {
|
|
75
|
-
Kind.CLASS: "
|
|
76
|
-
Kind.PORT: "
|
|
75
|
+
Kind.CLASS: "class",
|
|
76
|
+
Kind.PORT: "port",
|
|
77
77
|
Kind.DATACLASS: "dataclass",
|
|
78
|
-
Kind.MODEL: "
|
|
79
|
-
Kind.ALIAS: "
|
|
80
|
-
Kind.ENUM: "
|
|
81
|
-
Kind.ERROR: "
|
|
82
|
-
Kind.FUNCTION: "
|
|
78
|
+
Kind.MODEL: "model",
|
|
79
|
+
Kind.ALIAS: "alias",
|
|
80
|
+
Kind.ENUM: "enum",
|
|
81
|
+
Kind.ERROR: "exception",
|
|
82
|
+
Kind.FUNCTION: "function",
|
|
83
83
|
}
|
|
84
84
|
|
|
85
85
|
|
|
86
86
|
@dataclass(frozen=True, slots=True)
|
|
87
87
|
class Declaration:
|
|
88
|
-
"""
|
|
88
|
+
"""A top-level declaration: the name, the kind and the node.
|
|
89
89
|
|
|
90
|
-
`kind`
|
|
91
|
-
|
|
92
|
-
|
|
90
|
+
`kind` is empty when one file does not show the kind: a class with a base
|
|
91
|
+
from another module. Such a class still has a name, and a rule that looks at
|
|
92
|
+
the suffix uses it.
|
|
93
93
|
"""
|
|
94
94
|
|
|
95
95
|
name: str
|
|
@@ -98,10 +98,11 @@ class Declaration:
|
|
|
98
98
|
|
|
99
99
|
|
|
100
100
|
def declarations(*, tree: ast.Module) -> Iterator[Declaration]:
|
|
101
|
-
"""
|
|
101
|
+
"""Everything a module declares.
|
|
102
102
|
|
|
103
|
-
|
|
104
|
-
|
|
103
|
+
Imports, constants, `if TYPE_CHECKING` blocks and the docstring are left
|
|
104
|
+
out: they are allowed everywhere, and the placement rules have nothing to
|
|
105
|
+
say about them.
|
|
105
106
|
"""
|
|
106
107
|
for node in tree.body:
|
|
107
108
|
match node:
|
|
@@ -129,12 +130,12 @@ def declarations(*, tree: ast.Module) -> Iterator[Declaration]:
|
|
|
129
130
|
|
|
130
131
|
|
|
131
132
|
def _class(*, node: ast.ClassDef) -> Kind | None:
|
|
132
|
-
"""
|
|
133
|
+
"""The class's kind; `None` if one file does not show it.
|
|
133
134
|
|
|
134
|
-
|
|
135
|
-
`class CodeMismatchResponse(ErrorResponse)`
|
|
136
|
-
|
|
137
|
-
|
|
135
|
+
A base declared in another module is a kind that cannot be seen from here:
|
|
136
|
+
`class CodeMismatchResponse(ErrorResponse)` is a pydantic model, but that
|
|
137
|
+
can only be learned by reading that module. The rule is silent about such
|
|
138
|
+
a class: the stray helper it was written for usually has no base.
|
|
138
139
|
"""
|
|
139
140
|
bases = frozenset(names(nodes=node.bases))
|
|
140
141
|
if bases & ABSTRACT or _metaclass(node=node):
|
|
@@ -164,10 +165,11 @@ def _metaclass(*, node: ast.ClassDef) -> bool:
|
|
|
164
165
|
|
|
165
166
|
|
|
166
167
|
def _alias(*, node: ast.AnnAssign | ast.Assign) -> bool:
|
|
167
|
-
"""
|
|
168
|
+
"""An assignment that declares a name for a type.
|
|
168
169
|
|
|
169
|
-
|
|
170
|
-
`Row = dict[str, int]` —
|
|
170
|
+
Three kinds: annotated with `TypeAlias`, a call of a factory such as
|
|
171
|
+
`NewType`, and a bare `Row = dict[str, int]` — a name for a shape, not a
|
|
172
|
+
value.
|
|
171
173
|
"""
|
|
172
174
|
if isinstance(node, ast.AnnAssign) and name(node=node.annotation) == ALIAS_ANNOTATION:
|
|
173
175
|
return True
|
py_checks/checks/_layout.py
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""The project's layout: one block per directory.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
(`operation-shape`).
|
|
7
|
-
`use_cases`
|
|
8
|
-
|
|
3
|
+
Four rules speak of the same thing from four sides: what may lie here
|
|
4
|
+
(`class-modules`), what lives only here (`class-placement`), what a module must
|
|
5
|
+
declare (`required-class`) and what shape an operation has here
|
|
6
|
+
(`operation-shape`). Each used to have a table of its own, and one fact about
|
|
7
|
+
`use_cases` had to be written four times in four syntaxes, stitched together
|
|
8
|
+
by eye on a string key.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Now there is one block per directory, and the rules read their own columns
|
|
11
|
+
from it:
|
|
11
12
|
|
|
12
13
|
```toml
|
|
13
14
|
[layout."application/use_cases"]
|
|
@@ -17,10 +18,10 @@ required = true
|
|
|
17
18
|
operation = { method = "execute", max-arguments = 3 }
|
|
18
19
|
```
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
`application/use_cases`
|
|
23
|
-
|
|
21
|
+
The rules still know nothing of each other — they simply read one table. The
|
|
22
|
+
address in the heading is looked for as consecutive path parts, so
|
|
23
|
+
`application/use_cases` is found in a modular service too, where the path
|
|
24
|
+
starts with `modules/<name>/`, and `*` matches any one part.
|
|
24
25
|
"""
|
|
25
26
|
|
|
26
27
|
from __future__ import annotations
|
|
@@ -44,36 +45,42 @@ SECTION: Final = "layout"
|
|
|
44
45
|
|
|
45
46
|
|
|
46
47
|
class Orm(StrEnum):
|
|
47
|
-
"""
|
|
48
|
+
"""What a directory is to an ORM model.
|
|
48
49
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
50
|
+
The model's home and the place where it is built are two ends of one
|
|
51
|
+
convention, and writing them in a separate table would name the same two
|
|
52
|
+
directories a second time: the layout already knows them by name.
|
|
52
53
|
"""
|
|
53
54
|
|
|
54
|
-
#
|
|
55
|
-
#
|
|
55
|
+
# Models are declared here: anywhere else it is a table nobody expects at
|
|
56
|
+
# that address, and alembic's autogenerate sees only their package.
|
|
56
57
|
DECLARED = "declared"
|
|
57
58
|
|
|
58
|
-
#
|
|
59
|
+
# Models are built here: building a model means writing a row.
|
|
59
60
|
BUILT = "built"
|
|
60
61
|
|
|
61
62
|
|
|
62
63
|
class Operation(CheckSettings):
|
|
63
|
-
"""
|
|
64
|
-
|
|
65
|
-
`method`
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
`forbids`
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
64
|
+
"""The shape of an operation kept in this directory.
|
|
65
|
+
|
|
66
|
+
`method` is the only public door: a use case is asked for one thing, and a
|
|
67
|
+
second public method means a second operation sharing a constructor with
|
|
68
|
+
the first. Empty means the number of doors is not limited: a module's
|
|
69
|
+
service has as many as its entity has transitions.
|
|
70
|
+
|
|
71
|
+
`forbids` is the names of types an operation does not hold: `UnitOfWork` is
|
|
72
|
+
caught both as `IPlacementUnitOfWork` and as `UnitOfWorkFactory`, because
|
|
73
|
+
what is forbidden is holding the transaction, not spelling its name one
|
|
74
|
+
particular way.
|
|
75
|
+
|
|
76
|
+
`max_arguments` is how many arguments the entrance takes. A door carries
|
|
77
|
+
what came from outside, and an entrance longer than a few fields is a thing
|
|
78
|
+
with a name: a command, a query, a DTO.
|
|
79
|
+
|
|
80
|
+
`takes` is the suffix of what the entrance takes: `Query` in
|
|
81
|
+
`use_cases/queries` means every argument of the door is a `...Query`. The
|
|
82
|
+
split into commands and queries holds only while each side is handed its
|
|
83
|
+
own kind of input.
|
|
77
84
|
"""
|
|
78
85
|
|
|
79
86
|
method: str | None = None
|
|
@@ -82,23 +89,31 @@ class Operation(CheckSettings):
|
|
|
82
89
|
default=None,
|
|
83
90
|
gt=0,
|
|
84
91
|
)
|
|
92
|
+
takes: str | None = None
|
|
85
93
|
|
|
86
94
|
|
|
87
95
|
class Directory(CheckSettings):
|
|
88
|
-
"""
|
|
89
|
-
|
|
90
|
-
`only` —
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
`
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
`
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
`
|
|
100
|
-
|
|
101
|
-
`
|
|
96
|
+
"""What the project keeps in this directory.
|
|
97
|
+
|
|
98
|
+
`only` — the kinds that belong here, and nothing else sits beside them.
|
|
99
|
+
Written out empty, `only = []`, it means constants and nothing else;
|
|
100
|
+
left unset, it restricts nothing.
|
|
101
|
+
`home` — the kinds that belong ONLY here: a port declared at the other end
|
|
102
|
+
of the tree is a port the reader will not find.
|
|
103
|
+
`area` — the part of the tree within which home and name mean anything at
|
|
104
|
+
all: the rule about `dto` is written about the application layer, and a
|
|
105
|
+
dataclass in the bootstrap or in observability is just a way to put three
|
|
106
|
+
fields side by side.
|
|
107
|
+
`suffix` — what the class this directory exists for is called; it too
|
|
108
|
+
lives only here.
|
|
109
|
+
`required` — a module must declare such a class, first and alone.
|
|
110
|
+
`named` — every class of the `only` kinds here ends with `suffix`, as many
|
|
111
|
+
per module as the idea needs: `domain/value_objects` keeps `PriceValue`
|
|
112
|
+
and `CurrencyValue` side by side, and a bare `Price` beside them is the
|
|
113
|
+
one the reader will not recognise.
|
|
114
|
+
`operation` — the shape of an operation, if operations are kept here.
|
|
115
|
+
`orm` — what the directory is to an ORM model: its home or where it is built.
|
|
116
|
+
`base` — the base class by which a model is recognised in the models' home.
|
|
102
117
|
"""
|
|
103
118
|
|
|
104
119
|
only: tuple[Kind, ...] = ()
|
|
@@ -106,50 +121,61 @@ class Directory(CheckSettings):
|
|
|
106
121
|
area: str | None = None
|
|
107
122
|
suffix: str | None = None
|
|
108
123
|
required: bool = False
|
|
124
|
+
named: bool = False
|
|
109
125
|
operation: Operation | None = None
|
|
110
126
|
orm: Orm | None = None
|
|
111
127
|
base: str | None = None
|
|
112
128
|
|
|
129
|
+
@property
|
|
130
|
+
def restricted(self) -> bool:
|
|
131
|
+
"""Whether `only` was written: an empty list written out allows constants alone."""
|
|
132
|
+
return bool(self.only) or "only" in self.model_fields_set
|
|
133
|
+
|
|
113
134
|
@model_validator(mode="after")
|
|
114
135
|
def _named(self) -> Self:
|
|
115
|
-
"""
|
|
136
|
+
"""Obligation and shape rest on the name: without a suffix there is no checking them."""
|
|
116
137
|
if self.suffix is not None:
|
|
117
138
|
return self
|
|
118
139
|
if self.required:
|
|
119
|
-
message = "`required`
|
|
140
|
+
message = "`required` without `suffix`: it is unclear which class must be there"
|
|
141
|
+
raise ValueError(message)
|
|
142
|
+
if self.named:
|
|
143
|
+
message = "`named` without `suffix`: it is unclear what the classes are called"
|
|
120
144
|
raise ValueError(message)
|
|
121
145
|
if self.operation is not None:
|
|
122
|
-
message =
|
|
146
|
+
message = (
|
|
147
|
+
"`operation` without `suffix`: it is unclear which class is the operation here"
|
|
148
|
+
)
|
|
123
149
|
raise ValueError(message)
|
|
124
150
|
return self
|
|
125
151
|
|
|
126
152
|
@model_validator(mode="after")
|
|
127
153
|
def _claims(self) -> Self:
|
|
128
|
-
"""
|
|
154
|
+
"""An area narrows a claim: without a home and a name there is nothing to narrow."""
|
|
129
155
|
if self.area is not None and not self.home and self.suffix is None:
|
|
130
|
-
message = "`area`
|
|
156
|
+
message = "`area` without `home` and `suffix`: this directory claims nothing"
|
|
131
157
|
raise ValueError(message)
|
|
132
158
|
return self
|
|
133
159
|
|
|
134
160
|
@model_validator(mode="after")
|
|
135
161
|
def _declares(self) -> Self:
|
|
136
|
-
"""`base`
|
|
162
|
+
"""`base` is about the models' home: where they are built, there is nothing to spot."""
|
|
137
163
|
if self.base is not None and self.orm is not Orm.DECLARED:
|
|
138
|
-
message = '`base`
|
|
164
|
+
message = '`base` without `orm = "declared"`: the base is named by the models\' home'
|
|
139
165
|
raise ValueError(message)
|
|
140
166
|
return self
|
|
141
167
|
|
|
142
168
|
|
|
143
169
|
class Layout(CheckSettings):
|
|
144
|
-
"""
|
|
170
|
+
"""The `[layout]` section: a directory's address — and a block about it.
|
|
145
171
|
|
|
146
|
-
|
|
147
|
-
|
|
172
|
+
The keys come from the project, so the model accepts any: directory names
|
|
173
|
+
are data, not fields. What is checked is the content of the block.
|
|
148
174
|
"""
|
|
149
175
|
|
|
150
176
|
model_config = CheckSettings.model_config | {"extra": "allow"}
|
|
151
177
|
|
|
152
|
-
#
|
|
178
|
+
# pydantic's typed `extra`: the key is an address, the value a block.
|
|
153
179
|
__pydantic_extra__: dict[str, Directory] # type: ignore[assignment]
|
|
154
180
|
|
|
155
181
|
@property
|
|
@@ -162,7 +188,7 @@ def addressed(
|
|
|
162
188
|
layout: dict[str, Directory],
|
|
163
189
|
orm: Orm,
|
|
164
190
|
) -> tuple[str, ...]:
|
|
165
|
-
"""
|
|
191
|
+
"""The addresses that declared themselves this end of the ORM model convention."""
|
|
166
192
|
return tuple(address for address, directory in layout.items() if directory.orm is orm)
|
|
167
193
|
|
|
168
194
|
|
|
@@ -171,16 +197,16 @@ def innermost(
|
|
|
171
197
|
where: Place,
|
|
172
198
|
among: Iterable[tuple[str, Directory]],
|
|
173
199
|
) -> tuple[str, Directory] | None:
|
|
174
|
-
"""
|
|
200
|
+
"""The block of the innermost matched directory.
|
|
175
201
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
202
|
+
The deepest wins: `modules/betslip/application/services` beats
|
|
203
|
+
`application`. At equal depth, the longer address: a path says more about a
|
|
204
|
+
place than one name.
|
|
179
205
|
"""
|
|
180
206
|
matched = [
|
|
181
207
|
(depth, len(address), address, directory)
|
|
182
208
|
for address, directory in among
|
|
183
|
-
if (depth := where.
|
|
209
|
+
if (depth := where.reach(address=address)) is not None
|
|
184
210
|
]
|
|
185
211
|
if not matched:
|
|
186
212
|
return None
|
|
@@ -190,7 +216,7 @@ def innermost(
|
|
|
190
216
|
|
|
191
217
|
@dataclass(frozen=True, slots=True)
|
|
192
218
|
class Claim:
|
|
193
|
-
"""
|
|
219
|
+
"""Whose home this is and why the declaration asks to be in it."""
|
|
194
220
|
|
|
195
221
|
address: str
|
|
196
222
|
said: str
|
|
@@ -202,11 +228,11 @@ def claimants(
|
|
|
202
228
|
layout: dict[str, Directory],
|
|
203
229
|
where: Place,
|
|
204
230
|
) -> list[Claim]:
|
|
205
|
-
"""
|
|
231
|
+
"""The addresses that claim this declaration: by name or by kind.
|
|
206
232
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
233
|
+
A block with `area` claims only what lies inside the named part of the
|
|
234
|
+
tree: the convention about `dto` is written about the application layer,
|
|
235
|
+
and a dataclass in the bootstrap is not its to judge.
|
|
210
236
|
"""
|
|
211
237
|
found: list[Claim] = []
|
|
212
238
|
for address, directory in layout.items():
|
|
@@ -231,9 +257,11 @@ def _claim(
|
|
|
231
257
|
declared: Declaration,
|
|
232
258
|
directory: Directory,
|
|
233
259
|
) -> str | None:
|
|
234
|
-
"""
|
|
260
|
+
"""Why this address claims the declaration; `None` — it does not."""
|
|
235
261
|
if directory.suffix is not None and declared.name.endswith(directory.suffix):
|
|
236
|
-
return f"
|
|
262
|
+
return f"ends with {directory.suffix}"
|
|
237
263
|
if declared.kind is not None and declared.kind in directory.home:
|
|
238
|
-
|
|
264
|
+
said = declared.kind.said
|
|
265
|
+
# Every kind's name is a plain English noun, so the first letter decides.
|
|
266
|
+
return f"is {'an' if said[0] in 'aeiou' else 'a'} {said}"
|
|
239
267
|
return None
|