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.
Files changed (116) hide show
  1. py_checks/checks/__init__.py +15 -14
  2. py_checks/checks/_kind.py +34 -32
  3. py_checks/checks/_layout.py +100 -72
  4. py_checks/checks/_location.py +73 -31
  5. py_checks/checks/_names.py +25 -23
  6. py_checks/checks/api/__init__.py +4 -4
  7. py_checks/checks/api/_edge_declarations.py +80 -73
  8. py_checks/checks/api/_marker.py +1 -1
  9. py_checks/checks/calls/__init__.py +3 -3
  10. py_checks/checks/calls/_confined_functions.py +15 -14
  11. py_checks/checks/calls/_marker.py +1 -1
  12. py_checks/checks/database/__init__.py +7 -5
  13. py_checks/checks/database/_bound_checks.py +32 -31
  14. py_checks/checks/database/_confined_calls.py +23 -23
  15. py_checks/checks/database/_marker.py +1 -1
  16. py_checks/checks/database/_model_boundary.py +37 -36
  17. py_checks/checks/database/_model_columns.py +36 -36
  18. py_checks/checks/database/_raw_sql.py +40 -37
  19. py_checks/checks/database/_schema_drift.py +50 -47
  20. py_checks/checks/database/_statement_keys.py +29 -28
  21. py_checks/checks/effects/__init__.py +6 -5
  22. py_checks/checks/effects/_determinism.py +26 -23
  23. py_checks/checks/effects/_log_events.py +18 -18
  24. py_checks/checks/effects/_marker.py +1 -1
  25. py_checks/checks/errors/__init__.py +3 -3
  26. py_checks/checks/errors/_marker.py +1 -1
  27. py_checks/checks/errors/_refusals.py +39 -38
  28. py_checks/checks/hygiene/__init__.py +5 -4
  29. py_checks/checks/hygiene/_dependency_bounds.py +33 -33
  30. py_checks/checks/hygiene/_marker.py +1 -1
  31. py_checks/checks/imports/__init__.py +9 -9
  32. py_checks/checks/imports/_confined.py +15 -14
  33. py_checks/checks/imports/_marker.py +1 -1
  34. py_checks/checks/imports/_sealed.py +17 -28
  35. py_checks/checks/imports/_statements.py +5 -5
  36. py_checks/checks/placement/__init__.py +11 -11
  37. py_checks/checks/placement/_class_modules.py +32 -20
  38. py_checks/checks/placement/_class_placement.py +19 -17
  39. py_checks/checks/placement/_marker.py +1 -1
  40. py_checks/checks/placement/_operation_shape.py +140 -77
  41. py_checks/checks/placement/_required_class.py +77 -34
  42. py_checks/checks/signatures/__init__.py +6 -5
  43. py_checks/checks/signatures/_function_length.py +18 -17
  44. py_checks/checks/signatures/_functions.py +13 -12
  45. py_checks/checks/signatures/_keyword_only.py +23 -21
  46. py_checks/checks/signatures/_marker.py +1 -1
  47. py_checks/checks/signatures/_module_length.py +8 -8
  48. py_checks/checks/signatures/_nesting.py +20 -20
  49. py_checks/checks/signatures/_signature_layout.py +46 -47
  50. py_checks/checks/types/__init__.py +5 -4
  51. py_checks/checks/types/_annotation_shapes.py +20 -20
  52. py_checks/checks/types/_config_fields.py +44 -43
  53. py_checks/checks/types/_confined_types.py +26 -26
  54. py_checks/checks/types/_constant_annotations.py +18 -17
  55. py_checks/checks/types/_frozen_dataclasses.py +14 -13
  56. py_checks/checks/types/_marker.py +1 -1
  57. py_checks/cli/__init__.py +3 -3
  58. py_checks/cli/_app.py +3 -3
  59. py_checks/cli/_protocols.py +6 -5
  60. py_checks/cli/commands/__init__.py +6 -4
  61. py_checks/cli/commands/_doctor.py +104 -68
  62. py_checks/cli/commands/_explain.py +15 -14
  63. py_checks/cli/commands/_list.py +10 -10
  64. py_checks/cli/commands/_mutation.py +247 -0
  65. py_checks/cli/commands/_run.py +25 -26
  66. py_checks/cli/commands/_summary.py +3 -3
  67. py_checks/cli/commands/_sync.py +9 -9
  68. py_checks/config/__init__.py +7 -7
  69. py_checks/config/_base.py +11 -10
  70. py_checks/config/_config.py +33 -30
  71. py_checks/config/_constants.py +7 -7
  72. py_checks/config/_errors.py +5 -5
  73. py_checks/config/_loader.py +22 -21
  74. py_checks/config/_toml.py +5 -4
  75. py_checks/contracts/__init__.py +9 -9
  76. py_checks/contracts/_constants.py +7 -4
  77. py_checks/contracts/_layout.py +7 -6
  78. py_checks/contracts/_render.py +80 -31
  79. py_checks/contracts/_settings.py +13 -11
  80. py_checks/core/__init__.py +4 -4
  81. py_checks/core/_constants.py +7 -6
  82. py_checks/core/_discovery.py +6 -6
  83. py_checks/core/_edit.py +18 -15
  84. py_checks/core/_errors.py +4 -4
  85. py_checks/core/_fixer.py +5 -5
  86. py_checks/core/_format.py +7 -7
  87. py_checks/core/_markers.py +41 -37
  88. py_checks/core/_paths.py +14 -12
  89. py_checks/core/_protocols.py +33 -29
  90. py_checks/core/_registry.py +15 -13
  91. py_checks/core/_report.py +8 -7
  92. py_checks/core/_runner.py +18 -18
  93. py_checks/core/_settings.py +8 -8
  94. py_checks/core/_source.py +14 -13
  95. py_checks/core/_violation.py +15 -13
  96. py_checks/environment/__init__.py +6 -6
  97. py_checks/environment/_constants.py +1 -1
  98. py_checks/environment/_render.py +38 -37
  99. py_checks/environment/_settings.py +11 -10
  100. py_checks/mutation/__init__.py +34 -0
  101. py_checks/mutation/_baseline.py +47 -0
  102. py_checks/mutation/_constants.py +11 -0
  103. py_checks/mutation/_errors.py +12 -0
  104. py_checks/mutation/_gate.py +175 -0
  105. py_checks/mutation/_mutmut.py +162 -0
  106. py_checks/mutation/_process.py +44 -0
  107. py_checks/mutation/_scope.py +155 -0
  108. py_checks/mutation/_settings.py +54 -0
  109. py_checks/sync/__init__.py +9 -9
  110. py_checks/sync/_sync.py +11 -10
  111. {python_checks-0.5.0.dist-info → python_checks-0.7.0.dist-info}/METADATA +4 -1
  112. python_checks-0.7.0.dist-info/RECORD +117 -0
  113. {python_checks-0.5.0.dist-info → python_checks-0.7.0.dist-info}/WHEEL +1 -1
  114. python_checks-0.5.0.dist-info/RECORD +0 -107
  115. {python_checks-0.5.0.dist-info → python_checks-0.7.0.dist-info}/entry_points.txt +0 -0
  116. {python_checks-0.5.0.dist-info → python_checks-0.7.0.dist-info}/licenses/LICENSE +0 -0
@@ -1,20 +1,21 @@
1
- """Реализации правил, по пакету на группу.
1
+ """The rule implementations, one package per group.
2
2
 
3
- Внутри группы — по модулю на проверку. Правила, уехавшие в import-linter,
4
- ruff и alembic, сюда не переносятся; что и куда ушло, записано в
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`, помощник, который зовёт другого помощника, — `@classmethod`,
10
- чтобы звать через `cls`, а не по имени класса.
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
- принадлежит: «как этот узел зовут» — это `_names.py`, «где лежит этот файл» —
14
- `_location.py`, «что тут объявлено» — `_kind.py`. Шесть одинаковых `_name` по
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
- одну, есть `# check-ok: <код>: <причина>`.
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
- """Что объявлено в модуле: класс, порт, dataclass, алиас.
1
+ """What a module declares: a class, a port, a dataclass, an alias.
2
2
 
3
- Правила размещения говорят о видах объявлений, а не о синтаксисе: «в `dto/`
4
- лежат dataclass-ы», «в `ports/` — протоколы». Вид узнаётся один раз здесь, и
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
- # Исключение проекта наследуется от своего же корня (`class NotFound(DomainError)`),
31
- # а не от `Exception`, — но имя корня кончается так же, и по нему вид узнаётся,
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
- """Как вид называется в сообщении: `str.title` занят самим `str`."""
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
- Импорты, константы, блоки `if TYPE_CHECKING` и докстринг сюда не попадают:
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
- """Вид класса; `None`, если по одному файлу его не видно.
133
+ """The class's kind; `None` if one file does not show it.
133
134
 
134
- База, объявленная в другом модуле, — это вид, которого отсюда не видно:
135
- `class CodeMismatchResponse(ErrorResponse)` — pydantic-модель, но узнать
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
- Три вида: с аннотацией `TypeAlias`, вызов фабрики вроде `NewType`, и голое
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
@@ -1,13 +1,14 @@
1
- """Раскладка проекта: один блок на директорию.
1
+ """The project's layout: one block per directory.
2
2
 
3
- Четыре правила говорят об одной и той же вещи с четырёх сторон: что здесь
4
- может лежать (`class-modules`), что живёт только здесь (`class-placement`),
5
- что модуль обязан объявить (`required-class`) и какой формы тут операция
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
- с `modules/<имя>/`, а `*` подходит любому одному куску.
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
- """Чем директория приходится ORM-модели.
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
- # этому адресу, а autogenerate alembic видит только их пакет.
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` — имена типов, которых операция не держит: `UnitOfWork` ловится
71
- и как `IPlacementUnitOfWork`, и как `UnitOfWorkFactory`, потому что
72
- запрещено держать транзакцию, а не писать её имя одним конкретным образом.
73
-
74
- `max_arguments` — сколько аргументов занимает вход. Дверь несёт то, что
75
- пришло снаружи, и вход длиннее нескольких полей — вещь с именем: команда,
76
- запрос, DTO.
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
- `home` — виды, которым место ТОЛЬКО здесь: порт, объявленный в другом
92
- конце дерева, — это порт, которого читатель не найдёт.
93
- `area` — часть дерева, внутри которой дом и имя вообще о чём-то говорят:
94
- правило про `dto` написано про слой приложения, а dataclass в загрузчике
95
- или в наблюдаемости — просто способ сложить три поля рядом.
96
- `suffix` — как зовут класс, ради которого директория существует; он же
97
- живёт только здесь.
98
- `required` — модуль обязан объявить такой класс, первым и один.
99
- `operation` — форма операции, если здесь держат операции.
100
- `orm` — чем директория приходится ORM-модели: домом или местом сборки.
101
- `base` — базовый класс, по которому модель узнают в доме моделей.
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` без `suffix`: непонятно, какой класс обязан быть"
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 = "`operation` без `suffix`: непонятно, какой класс здесь операция"
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` без `home` и `suffix`: эта директория ни на что не притязает"
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` без `orm = "declared"`: базу называет дом моделей'
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
- """Секция `[layout]`: адрес директории — и блок про неё.
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
- # Типизированный `extra` pydantic: ключ — адрес, значение — блок.
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
- """Адреса, объявившие себя этим концом соглашения про ORM-модель."""
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
- Побеждает самая глубокая: `modules/betslip/application/services` важнее,
177
- чем `application`. При равной глубине — более длинный адрес: путь говорит о
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.within(directory=address)) is not None
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
- Блок с `area` притязает только на то, что лежит внутри названной части
208
- дерева: соглашение про `dto` написано про слой приложения, и dataclass в
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
- """Почему этот адрес считает объявление своим; `None` — не считает."""
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"кончается на {directory.suffix}"
262
+ return f"ends with {directory.suffix}"
237
263
  if declared.kind is not None and declared.kind in directory.home:
238
- return f"— {declared.kind.said}"
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