python-checks 0.9.0__py3-none-any.whl → 0.11.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.
@@ -114,6 +114,9 @@ class Directory(CheckSettings):
114
114
  `operation` — the shape of an operation, if operations are kept here.
115
115
  `orm` — what the directory is to an ORM model: its home or where it is built.
116
116
  `base` — the base class by which a model is recognised in the models' home.
117
+ `optional` — the directory may not exist yet: the block says where code
118
+ goes, not where it already is, and `doctor` does not ask the tree for it.
119
+ The rules judge it as soon as a file turns up there.
117
120
  """
118
121
 
119
122
  only: tuple[Kind, ...] = ()
@@ -125,6 +128,7 @@ class Directory(CheckSettings):
125
128
  operation: Operation | None = None
126
129
  orm: Orm | None = None
127
130
  base: str | None = None
131
+ optional: bool = False
128
132
 
129
133
  @property
130
134
  def restricted(self) -> bool:
@@ -1,7 +1,8 @@
1
1
  """Repository hygiene.
2
2
 
3
3
  A dependency declares a ceiling: without one the version is chosen by the
4
- resolver, not by a person. The rest of this group is covered by something
4
+ resolver, not by a person. A translated document still says what its English
5
+ source says. The rest of this group is covered by something
5
6
  other than checks — `.env.example` is generated from the settings models, and
6
7
  `CLAUDE.md` is a symlink to `AGENTS.md`.
7
8
  """
@@ -11,5 +12,6 @@ from py_checks.checks.hygiene._dependency_bounds import (
11
12
  DependencyBoundsSettings,
12
13
  )
13
14
  from py_checks.checks.hygiene._marker import MARKER
15
+ from py_checks.checks.hygiene._translations import Translations
14
16
 
15
- __all__ = ["MARKER", "DependencyBounds", "DependencyBoundsSettings"]
17
+ __all__ = ["MARKER", "DependencyBounds", "DependencyBoundsSettings", "Translations"]
@@ -0,0 +1,169 @@
1
+ """A translated document still says what its English source says."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING, ClassVar, Final
6
+
7
+ from py_checks.checks.hygiene._marker import MARKER
8
+ from py_checks.core import Scope, Violation, settings_as
9
+ from py_checks.translations import (
10
+ SECTION,
11
+ TranslationError,
12
+ TranslationsSettings,
13
+ fingerprint,
14
+ selected,
15
+ source_of,
16
+ stamped,
17
+ tracked,
18
+ translation_of,
19
+ )
20
+
21
+ if TYPE_CHECKING:
22
+ from collections.abc import Iterator
23
+ from pathlib import Path
24
+
25
+ from py_checks.config import CheckSettings
26
+
27
+ CODE: Final = SECTION
28
+
29
+ FIRST: Final = 1
30
+
31
+
32
+ class Translations:
33
+ """Fails when a translation is missing or no longer matches its source.
34
+
35
+ A translation goes stale the moment the English changes, and nothing
36
+ tells anyone: its reader reads a document that is no longer true. A
37
+ document nobody translated is the same problem one step earlier. So the
38
+ check refuses both, the way `py-checks sync --check` refuses a generated
39
+ file that no longer matches what it is built from.
40
+
41
+ English is the source, and each language mirrors the repository under
42
+ `docs/langs/<lang>/` by the same path: `docs/testing.md` is translated in
43
+ `docs/langs/ru/docs/testing.md`. The first line of a translation is the
44
+ SHA-256 of the source as it was when translated, written by
45
+ `py-checks translations stamp <translation>` — never by `run --fix`, which
46
+ would bless a translation nobody updated.
47
+
48
+ Refused: a selected file with no translation; a translation whose source
49
+ changed since; a translation whose source is gone or no longer selected;
50
+ a first line that is not a fingerprint.
51
+
52
+ Candidates are the files git knows and does not ignore, so `.venv/` never
53
+ needs excluding, and `docs/langs/` is never asked for its own translation.
54
+
55
+ Settings: `langs`, `files`.
56
+ """
57
+
58
+ code: ClassVar[str] = CODE
59
+ Settings: ClassVar[type[CheckSettings]] = TranslationsSettings
60
+ scope: ClassVar[Scope] = Scope.PROJECT
61
+ marker: ClassVar[str] = MARKER
62
+
63
+ @classmethod
64
+ def run(
65
+ cls,
66
+ *,
67
+ root: Path,
68
+ settings: CheckSettings,
69
+ ) -> Iterator[Violation]:
70
+ limits = settings_as(
71
+ settings=settings,
72
+ model=TranslationsSettings,
73
+ code=CODE,
74
+ )
75
+ if not limits.langs or not limits.files:
76
+ return
77
+ try:
78
+ paths = tracked(root=root)
79
+ except TranslationError as error:
80
+ yield cls._says(
81
+ path=root,
82
+ message=str(error),
83
+ )
84
+ return
85
+ sources = selected(
86
+ paths=paths,
87
+ files=limits.files,
88
+ )
89
+ for lang in limits.langs:
90
+ yield from cls._missing_or_stale(
91
+ root=root,
92
+ sources=sources,
93
+ lang=lang,
94
+ )
95
+ yield from cls._orphans(
96
+ root=root,
97
+ paths=paths,
98
+ sources=frozenset(sources),
99
+ lang=lang,
100
+ )
101
+
102
+ @classmethod
103
+ def _missing_or_stale(
104
+ cls,
105
+ *,
106
+ root: Path,
107
+ sources: list[str],
108
+ lang: str,
109
+ ) -> Iterator[Violation]:
110
+ """Every selected source: translated, and translated from what it says now."""
111
+ for source in sources:
112
+ translation = translation_of(
113
+ source=source,
114
+ lang=lang,
115
+ )
116
+ path = root / translation
117
+ if not path.is_file():
118
+ yield cls._says(
119
+ path=root / source,
120
+ message=f"{source} has no {lang} translation: {translation}",
121
+ )
122
+ continue
123
+ digest = stamped(path=path)
124
+ if digest is None:
125
+ yield cls._says(
126
+ path=path,
127
+ message=(
128
+ f"{translation}: the first line is not a fingerprint; after translating, "
129
+ f"run `py-checks translations stamp {translation}`"
130
+ ),
131
+ )
132
+ elif digest != fingerprint(path=root / source):
133
+ yield cls._says(
134
+ path=path,
135
+ message=f"{source} changed since {translation} was translated",
136
+ )
137
+
138
+ @classmethod
139
+ def _orphans(
140
+ cls,
141
+ *,
142
+ root: Path,
143
+ paths: list[str],
144
+ sources: frozenset[str],
145
+ lang: str,
146
+ ) -> Iterator[Violation]:
147
+ """A translation whose source is gone or no longer selected."""
148
+ for path in paths:
149
+ pair = source_of(translation=path)
150
+ if pair is None or pair[0] != lang or pair[1] in sources:
151
+ continue
152
+ yield cls._says(
153
+ path=root / path,
154
+ message=f"{path} translates nothing",
155
+ )
156
+
157
+ @staticmethod
158
+ def _says(
159
+ *,
160
+ path: Path,
161
+ message: str,
162
+ ) -> Violation:
163
+ return Violation(
164
+ path=path,
165
+ line=FIRST,
166
+ column=FIRST,
167
+ code=CODE,
168
+ message=message,
169
+ )
@@ -0,0 +1,442 @@
1
+ """Who calls a function: what `--fix` must rewrite before a parameter becomes named.
2
+
3
+ A `*` in a signature turns every positional call into a type error, and the
4
+ calls live in other modules, in tests, behind an import alias. The rule finds
5
+ them in two steps. A plain walk over the tree collects every place the name
6
+ is written — cheap and complete, but blind to whose name it is. jedi then
7
+ says, for each place, whose it is: ours, someone else's (`dict.get`), or
8
+ nobody knows. "Nobody knows" stops the fix: a call that cannot be told apart
9
+ is a call that could be broken, and a fix that cannot repair every caller is
10
+ not applied at all.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import ast
16
+ import os
17
+ import subprocess
18
+ from collections import defaultdict
19
+ from dataclasses import dataclass, replace
20
+ from pathlib import Path
21
+ from typing import TYPE_CHECKING, Final, Protocol, cast
22
+
23
+ import jedi # pyright: ignore[reportMissingTypeStubs] - jedi ships no stubs; `Found` types what is read
24
+
25
+ from py_checks.checks._names import names as named
26
+ from py_checks.checks.signatures._functions import receiver
27
+ from py_checks.checks.signatures._stops import stops
28
+ from py_checks.checks.signatures._targets import following, project_modules, relative, violated
29
+ from py_checks.core import Edit, Patch, Repair, column
30
+
31
+ if TYPE_CHECKING:
32
+ from collections.abc import Iterable, Iterator, Sequence
33
+
34
+ from py_checks.checks.signatures._targets import Module, Star, Target
35
+ from py_checks.core import Violation
36
+
37
+
38
+ VENV: Final = ".venv"
39
+
40
+
41
+ VIRTUAL_ENV: Final = "VIRTUAL_ENV"
42
+
43
+ # Only what is committed: an untracked `.venv` without a `.gitignore` is still
44
+ # one's own, made on this machine.
45
+ COMMITTED: Final = ("git", "ls-files", "--cached", "--")
46
+
47
+
48
+ CLASSMETHOD: Final = "classmethod"
49
+
50
+
51
+ class Found(Protocol):
52
+ """What the fix reads of a jedi definition: the file and the line it is in."""
53
+
54
+ @property
55
+ def module_path(self) -> Path | None: ...
56
+
57
+ @property
58
+ def line(self) -> int | None: ...
59
+
60
+
61
+ @dataclass(frozen=True, slots=True)
62
+ class Site:
63
+ """A place a target's name is written: a call or a mention."""
64
+
65
+ path: Path
66
+ node: ast.Name | ast.Attribute
67
+ call: ast.Call | None
68
+ name: str
69
+
70
+
71
+ def callers(
72
+ *,
73
+ violations: Sequence[Violation],
74
+ root: Path,
75
+ source: Path,
76
+ star: Star,
77
+ ) -> Repair:
78
+ """The fix for every violation whose callers can all be found, and the rest left."""
79
+ modules = project_modules(root=root)
80
+ fixed, left = violated(
81
+ violations=violations,
82
+ modules=modules,
83
+ )
84
+ followers, unmatched = following(
85
+ targets=fixed,
86
+ modules=modules,
87
+ source=source,
88
+ star=star,
89
+ root=root,
90
+ )
91
+ targets = [*fixed, *followers]
92
+ # The definition's own reason first: "called through its class" says more
93
+ # about a constructor than any double of the same name does.
94
+ stopped = stops(
95
+ targets=targets,
96
+ modules=modules,
97
+ root=root,
98
+ )
99
+ for family, reason in unmatched.items():
100
+ stopped.setdefault(family, reason)
101
+ edits = _calls(
102
+ targets=targets,
103
+ modules=modules,
104
+ project=_project(
105
+ root=root,
106
+ source=source,
107
+ ),
108
+ stopped=stopped,
109
+ root=root,
110
+ )
111
+ return _repair(
112
+ targets=targets,
113
+ edits=edits,
114
+ stopped=stopped,
115
+ left=left,
116
+ )
117
+
118
+
119
+ def _repair(
120
+ *,
121
+ targets: Sequence[Target],
122
+ edits: dict[tuple[str, ...], list[Patch]],
123
+ stopped: dict[tuple[str, ...], str],
124
+ left: list[Violation],
125
+ ) -> Repair:
126
+ """One patch set per family, shared by its members: they stand or fall together."""
127
+ members: dict[tuple[str, ...], list[Target]] = defaultdict(list)
128
+ for target in targets:
129
+ members[target.family].append(target)
130
+ repair = Repair(
131
+ patches={},
132
+ left=list(left),
133
+ )
134
+ for family, group in members.items():
135
+ violated = [target.violation for target in group if target.violation is not None]
136
+ if family in stopped:
137
+ repair.left.extend(
138
+ replace(
139
+ violation,
140
+ message=f"{violation.message}; not fixed: {stopped[family]}",
141
+ )
142
+ for violation in violated
143
+ )
144
+ continue
145
+ shared = (
146
+ *(
147
+ Patch(
148
+ path=target.path,
149
+ edit=target.edit,
150
+ )
151
+ for target in group
152
+ ),
153
+ *edits.get(family, ()),
154
+ )
155
+ repair.patches.update((violation, shared) for violation in violated)
156
+ return repair
157
+
158
+
159
+ def _project(
160
+ *,
161
+ root: Path,
162
+ source: Path,
163
+ ) -> jedi.Project:
164
+ """jedi over the project, in the project's own environment when there is one.
165
+
166
+ A hook runs in an environment of its own, where neither the project nor
167
+ its libraries are installed: without the project's `.venv` a library call
168
+ resolves to nothing and stops the fix of every function sharing its name.
169
+ """
170
+ environment = _environment(root=root)
171
+ return jedi.Project(
172
+ path=root,
173
+ environment_path=environment,
174
+ added_sys_path=(str(source),),
175
+ )
176
+
177
+
178
+ def _environment(*, root: Path) -> str | None:
179
+ """The interpreter jedi starts: the project's `.venv`, when git vouches for it.
180
+
181
+ jedi runs that interpreter to learn its paths, so the fix runs whatever
182
+ lies at `.venv/bin/python`. A `.venv` of one's own is not in git's index;
183
+ one that came with the repository — or with an archive git cannot speak
184
+ for — is someone else's program, and the fix stays in its own environment:
185
+ fewer calls resolved, nothing run.
186
+ """
187
+ venv = root / VENV
188
+ if venv.is_dir() and _local(root=root):
189
+ return str(venv)
190
+ return os.environ.get(VIRTUAL_ENV) or None
191
+
192
+
193
+ def _local(*, root: Path) -> bool:
194
+ """Whether git confirms nothing under `.venv` is committed; no answer is a no."""
195
+ try:
196
+ listed = subprocess.run( # noqa: S603 — a fixed list of arguments, no shell
197
+ [*COMMITTED, VENV],
198
+ cwd=root,
199
+ capture_output=True,
200
+ check=True,
201
+ )
202
+ except OSError, subprocess.CalledProcessError:
203
+ return False
204
+ return not listed.stdout.strip()
205
+
206
+
207
+ def _calls(
208
+ *,
209
+ targets: Sequence[Target],
210
+ modules: Sequence[Module],
211
+ project: jedi.Project,
212
+ stopped: dict[tuple[str, ...], str],
213
+ root: Path,
214
+ ) -> dict[tuple[str, ...], list[Patch]]:
215
+ """The call edits of every family; a family that meets a doubtful place is stopped."""
216
+ index = {(target.path, target.definition.node.lineno): target for target in targets}
217
+ # A stopped family needs no more reasons: its places are not worth a lookup.
218
+ wanted = {target.name for target in targets if target.family not in stopped}
219
+ edits: dict[tuple[str, ...], list[Patch]] = defaultdict(list)
220
+ for module in modules:
221
+ sites = list(
222
+ _sites(
223
+ module=module,
224
+ wanted=wanted,
225
+ )
226
+ )
227
+ if not sites:
228
+ continue
229
+ script = jedi.Script(
230
+ code=module.text,
231
+ path=module.path,
232
+ project=project,
233
+ )
234
+ lines = module.text.splitlines()
235
+ for site in sites:
236
+ _place(
237
+ site=site,
238
+ found=_resolved(
239
+ site=site,
240
+ script=script,
241
+ lines=lines,
242
+ index=index,
243
+ ),
244
+ lines=lines,
245
+ targets=targets,
246
+ edits=edits,
247
+ stopped=stopped,
248
+ where=relative(
249
+ path=site.path,
250
+ line=site.node.lineno,
251
+ root=root,
252
+ ),
253
+ )
254
+ return edits
255
+
256
+
257
+ def _resolved(
258
+ *,
259
+ site: Site,
260
+ script: jedi.Script,
261
+ lines: Sequence[str],
262
+ index: dict[tuple[Path, int], Target],
263
+ ) -> list[Target] | None:
264
+ """The targets this place names; `None` when nobody knows whose name it is.
265
+
266
+ An empty list is someone else's name: `dict.get`, a library, a function of
267
+ the project the fix does not change. A place that names a target and
268
+ something else at once — a union type — is as good as unknown.
269
+ """
270
+ line, offset = _point(node=site.node)
271
+ found = _goto(
272
+ script=script,
273
+ line=line,
274
+ column=column(
275
+ line=lines[line - 1],
276
+ offset=offset,
277
+ )
278
+ - 1,
279
+ )
280
+ if not found:
281
+ return None
282
+ hits = [
283
+ index.get((Path(one.module_path).resolve(), one.line))
284
+ for one in found
285
+ if one.module_path is not None and one.line is not None
286
+ ]
287
+ mine = [hit for hit in hits if hit is not None]
288
+ if mine and len(mine) < len(found):
289
+ return None
290
+ return mine
291
+
292
+
293
+ def _goto(
294
+ *,
295
+ script: jedi.Script,
296
+ line: int,
297
+ column: int,
298
+ ) -> list[Found]:
299
+ """Where jedi says the name at this point is defined; jedi ships no type hints."""
300
+ found = script.goto( # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
301
+ line,
302
+ column,
303
+ follow_imports=True,
304
+ )
305
+ return cast("list[Found]", found)
306
+
307
+
308
+ def _place(
309
+ *,
310
+ site: Site,
311
+ found: list[Target] | None,
312
+ lines: Sequence[str],
313
+ targets: Sequence[Target],
314
+ edits: dict[tuple[str, ...], list[Patch]],
315
+ stopped: dict[tuple[str, ...], str],
316
+ where: str,
317
+ ) -> None:
318
+ """Record what one place means for the families its name could belong to."""
319
+ if found is None:
320
+ for target in targets:
321
+ if target.name == site.name:
322
+ stopped.setdefault(target.family, f"{where} cannot be resolved")
323
+ return
324
+ for target in found:
325
+ reason, made = _rewritten(
326
+ site=site,
327
+ target=target,
328
+ lines=lines,
329
+ )
330
+ if reason is not None:
331
+ stopped.setdefault(target.family, f"{where} {reason}")
332
+ else:
333
+ edits[target.family].extend(made)
334
+
335
+
336
+ def _rewritten(
337
+ *,
338
+ site: Site,
339
+ target: Target,
340
+ lines: Sequence[str],
341
+ ) -> tuple[str | None, list[Patch]]:
342
+ """The call with its positional arguments named, or why it cannot be."""
343
+ call = site.call
344
+ if call is None:
345
+ return "passes it as a value", []
346
+ if any(isinstance(argument, ast.Starred) for argument in call.args):
347
+ return "unpacks arguments into it", []
348
+ if _through_class(
349
+ site=site,
350
+ target=target,
351
+ ):
352
+ return "calls it through the class, receiver included", []
353
+ moved = call.args[target.kept :]
354
+ if len(moved) > len(target.names):
355
+ return "passes more arguments than it takes", []
356
+ return None, [
357
+ Patch(
358
+ path=site.path,
359
+ edit=Edit(
360
+ line=argument.lineno,
361
+ column=(
362
+ at := column(
363
+ line=lines[argument.lineno - 1],
364
+ offset=argument.col_offset,
365
+ )
366
+ ),
367
+ end_line=argument.lineno,
368
+ end_column=at,
369
+ text=f"{parameter}=",
370
+ ),
371
+ )
372
+ for argument, parameter in zip(moved, target.names, strict=False)
373
+ ]
374
+
375
+
376
+ def _through_class(
377
+ *,
378
+ site: Site,
379
+ target: Target,
380
+ ) -> bool:
381
+ """`Repo.get(repo, key)`: the receiver is the first positional argument."""
382
+ if not isinstance(site.node, ast.Attribute) or not isinstance(site.node.value, ast.Name):
383
+ return False
384
+ plain = target.definition.method and receiver(definition=target.definition) == 1
385
+ if not plain or CLASSMETHOD in set(named(nodes=target.definition.node.decorator_list)):
386
+ return False
387
+ return site.node.value.id[:1].isupper()
388
+
389
+
390
+ def _sites(
391
+ *,
392
+ module: Module,
393
+ wanted: set[str],
394
+ ) -> Iterator[Site]:
395
+ """Every place in the module where one of the wanted names is written.
396
+
397
+ `from orders import price as quote` makes `quote` a place of `price`.
398
+ """
399
+ if module.tree is None:
400
+ return
401
+ aliases = dict(
402
+ _aliases(
403
+ tree=module.tree,
404
+ wanted=wanted,
405
+ )
406
+ )
407
+ callees = {id(node.func): node for node in ast.walk(module.tree) if isinstance(node, ast.Call)}
408
+ for node in ast.walk(module.tree):
409
+ match node:
410
+ case ast.Name(id=name) if name in wanted or name in aliases:
411
+ spelled = aliases.get(name, name)
412
+ case ast.Attribute(attr=name) if name in wanted:
413
+ spelled = name
414
+ case _:
415
+ continue
416
+ yield Site(
417
+ path=module.path,
418
+ node=node,
419
+ call=callees.get(id(node)),
420
+ name=spelled,
421
+ )
422
+
423
+
424
+ def _aliases(
425
+ *,
426
+ tree: ast.Module,
427
+ wanted: set[str],
428
+ ) -> Iterable[tuple[str, str]]:
429
+ for node in ast.walk(tree):
430
+ if isinstance(node, ast.ImportFrom):
431
+ for alias in node.names:
432
+ if alias.asname and alias.name in wanted:
433
+ yield alias.asname, alias.name
434
+
435
+
436
+ def _point(*, node: ast.Name | ast.Attribute) -> tuple[int, int]:
437
+ """Where the name itself starts: for `repo.get`, the `get`, not the `repo`."""
438
+ if isinstance(node, ast.Name):
439
+ return node.lineno, node.col_offset
440
+ end_line = node.end_lineno or node.lineno
441
+ end = node.end_col_offset or 0
442
+ return end_line, end - len(node.attr.encode("utf-8"))