python-checks 0.9.0__py3-none-any.whl → 0.10.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/hygiene/__init__.py +4 -2
- py_checks/checks/hygiene/_translations.py +169 -0
- py_checks/cli/commands/__init__.py +2 -0
- py_checks/cli/commands/_doctor.py +37 -1
- py_checks/cli/commands/_translations.py +98 -0
- py_checks/translations/__init__.py +30 -0
- py_checks/translations/_constants.py +15 -0
- py_checks/translations/_errors.py +7 -0
- py_checks/translations/_settings.py +22 -0
- py_checks/translations/_stamp.py +59 -0
- py_checks/translations/_tree.py +104 -0
- {python_checks-0.9.0.dist-info → python_checks-0.10.0.dist-info}/METADATA +7 -4
- {python_checks-0.9.0.dist-info → python_checks-0.10.0.dist-info}/RECORD +16 -8
- {python_checks-0.9.0.dist-info → python_checks-0.10.0.dist-info}/WHEEL +1 -1
- {python_checks-0.9.0.dist-info → python_checks-0.10.0.dist-info}/entry_points.txt +1 -0
- {python_checks-0.9.0.dist-info → python_checks-0.10.0.dist-info}/licenses/LICENSE +0 -0
|
@@ -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.
|
|
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
|
+
)
|
|
@@ -14,6 +14,7 @@ from py_checks.cli.commands._list import register as register_list
|
|
|
14
14
|
from py_checks.cli.commands._mutation import register as register_mutation
|
|
15
15
|
from py_checks.cli.commands._run import register as register_run
|
|
16
16
|
from py_checks.cli.commands._sync import register as register_sync
|
|
17
|
+
from py_checks.cli.commands._translations import register as register_translations
|
|
17
18
|
|
|
18
19
|
REGISTRARS: Final[tuple[Registrar, ...]] = (
|
|
19
20
|
register_run,
|
|
@@ -22,6 +23,7 @@ REGISTRARS: Final[tuple[Registrar, ...]] = (
|
|
|
22
23
|
register_sync,
|
|
23
24
|
register_doctor,
|
|
24
25
|
register_mutation,
|
|
26
|
+
register_translations,
|
|
25
27
|
)
|
|
26
28
|
|
|
27
29
|
__all__ = ["REGISTRARS", "Registrar"]
|
|
@@ -16,6 +16,8 @@ from py_checks.contracts import SECTION as CONTRACTS
|
|
|
16
16
|
from py_checks.core import ANY, EXIT_OK, EXIT_VIOLATION, SEPARATOR, available, depth, section_of
|
|
17
17
|
from py_checks.environment import SECTION as ENV_EXAMPLE
|
|
18
18
|
from py_checks.mutation import SECTION as MUTATION
|
|
19
|
+
from py_checks.translations import SECTION as TRANSLATIONS
|
|
20
|
+
from py_checks.translations import TranslationError, TranslationsSettings, dead, tracked
|
|
19
21
|
|
|
20
22
|
if TYPE_CHECKING:
|
|
21
23
|
from collections.abc import Iterator
|
|
@@ -51,12 +53,17 @@ class Complaint:
|
|
|
51
53
|
|
|
52
54
|
def doctor() -> None:
|
|
53
55
|
"""Check the settings themselves: typos, dead addresses, silent rules."""
|
|
54
|
-
|
|
56
|
+
root = find_root(start=Path.cwd())
|
|
57
|
+
config = load(root=root)
|
|
55
58
|
found = [
|
|
56
59
|
*_unknown(config=config),
|
|
57
60
|
*_ignored(config=config),
|
|
58
61
|
*_silent(config=config),
|
|
59
62
|
*_nowhere(config=config),
|
|
63
|
+
*_idle(
|
|
64
|
+
config=config,
|
|
65
|
+
root=root,
|
|
66
|
+
),
|
|
60
67
|
]
|
|
61
68
|
# A long name is not broken mid-word: the reader will copy it.
|
|
62
69
|
console = Console(soft_wrap=True)
|
|
@@ -266,6 +273,35 @@ def _answers(
|
|
|
266
273
|
return True
|
|
267
274
|
|
|
268
275
|
|
|
276
|
+
def _idle(
|
|
277
|
+
*,
|
|
278
|
+
config: Config,
|
|
279
|
+
root: Path,
|
|
280
|
+
) -> Iterator[Complaint]:
|
|
281
|
+
"""A translation pattern that changes nothing: without it, the same files are selected.
|
|
282
|
+
|
|
283
|
+
It catches a pattern that selects nothing and a `!` that excludes nothing —
|
|
284
|
+
`!.github/` under a `*.md` takes the directory out, not the files in it.
|
|
285
|
+
"""
|
|
286
|
+
table = config.checks.get(TRANSLATIONS)
|
|
287
|
+
if table is None:
|
|
288
|
+
return
|
|
289
|
+
try:
|
|
290
|
+
files = TranslationsSettings.model_validate(table).files
|
|
291
|
+
paths = tracked(root=root)
|
|
292
|
+
except ValueError, TranslationError:
|
|
293
|
+
return
|
|
294
|
+
named = prefix(source=config.origin)
|
|
295
|
+
for pattern in dead(
|
|
296
|
+
paths=paths,
|
|
297
|
+
files=files,
|
|
298
|
+
):
|
|
299
|
+
yield Complaint(
|
|
300
|
+
said="pattern that changes nothing",
|
|
301
|
+
about=f"[{named}{TRANSLATIONS}] — {pattern!r} selects or excludes no file",
|
|
302
|
+
)
|
|
303
|
+
|
|
304
|
+
|
|
269
305
|
def _addressed(*, config: Config) -> Iterator[tuple[str, str, bool]]:
|
|
270
306
|
"""The addresses written in the settings, and whether each is a zone.
|
|
271
307
|
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""The `translations` command: `stamp` a translation with its source's fingerprint."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Annotated
|
|
7
|
+
|
|
8
|
+
import typer
|
|
9
|
+
from rich.console import Console
|
|
10
|
+
|
|
11
|
+
from py_checks.config import find_root
|
|
12
|
+
from py_checks.core import EXIT_OK, EXIT_VIOLATION
|
|
13
|
+
from py_checks.translations import TranslationError, stamp
|
|
14
|
+
|
|
15
|
+
Paths = Annotated[
|
|
16
|
+
list[Path],
|
|
17
|
+
typer.Argument(help="the translations to stamp, under docs/langs/<lang>/"),
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
translations = typer.Typer(
|
|
21
|
+
no_args_is_help=True,
|
|
22
|
+
help="Translated documents: each one says which version of its source it was made from.",
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
console = Console(soft_wrap=True)
|
|
26
|
+
errors = Console(
|
|
27
|
+
stderr=True,
|
|
28
|
+
soft_wrap=True,
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@translations.command("stamp")
|
|
33
|
+
def stamped( # check-ok: keyword-only-arguments: typer parses the command's signature
|
|
34
|
+
paths: Paths,
|
|
35
|
+
) -> None:
|
|
36
|
+
"""Write the fingerprint of each translation's source on its first line.
|
|
37
|
+
|
|
38
|
+
Only the translations named, and only ones that exist: the translator
|
|
39
|
+
writes the translation, then stamps it. `run --fix` never does this — a fix
|
|
40
|
+
that rewrote the hash would bless a translation nobody updated.
|
|
41
|
+
"""
|
|
42
|
+
root = find_root(start=Path.cwd())
|
|
43
|
+
refused = 0
|
|
44
|
+
for path in paths:
|
|
45
|
+
try:
|
|
46
|
+
translation = _within(
|
|
47
|
+
root=root,
|
|
48
|
+
path=path,
|
|
49
|
+
)
|
|
50
|
+
stamp(
|
|
51
|
+
root=root,
|
|
52
|
+
translation=translation,
|
|
53
|
+
)
|
|
54
|
+
except TranslationError as error:
|
|
55
|
+
_say(
|
|
56
|
+
console=errors,
|
|
57
|
+
text=str(error),
|
|
58
|
+
)
|
|
59
|
+
refused += 1
|
|
60
|
+
continue
|
|
61
|
+
_say(
|
|
62
|
+
console=console,
|
|
63
|
+
text=f"stamped {translation}",
|
|
64
|
+
)
|
|
65
|
+
raise typer.Exit(EXIT_VIOLATION if refused else EXIT_OK)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _within(
|
|
69
|
+
*,
|
|
70
|
+
root: Path,
|
|
71
|
+
path: Path,
|
|
72
|
+
) -> str:
|
|
73
|
+
"""The path from the repository's root, the way the check names it."""
|
|
74
|
+
try:
|
|
75
|
+
return path.resolve().relative_to(root.resolve()).as_posix()
|
|
76
|
+
except ValueError as error:
|
|
77
|
+
message = f"{path} lies outside the project at {root}"
|
|
78
|
+
raise TranslationError(message) from error
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _say(
|
|
82
|
+
*,
|
|
83
|
+
console: Console,
|
|
84
|
+
text: str,
|
|
85
|
+
) -> None:
|
|
86
|
+
"""Print as is: a line is a path, and brackets in it are not markup."""
|
|
87
|
+
console.print(
|
|
88
|
+
text,
|
|
89
|
+
markup=False,
|
|
90
|
+
highlight=False,
|
|
91
|
+
)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def register(*, app: typer.Typer) -> None:
|
|
95
|
+
app.add_typer(
|
|
96
|
+
translations,
|
|
97
|
+
name="translations",
|
|
98
|
+
)
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Translated documents and the English sources they were translated from.
|
|
2
|
+
|
|
3
|
+
English is the source. Each language mirrors the repository under
|
|
4
|
+
`docs/langs/<lang>/`, by the same path, so a translation's path alone says
|
|
5
|
+
which file it belongs to. Its first line is the SHA-256 of the source's bytes
|
|
6
|
+
as they were when it was translated: the hash changes exactly when the source
|
|
7
|
+
does, which is exactly when the translation goes stale. A date moves with
|
|
8
|
+
`touch` and a rebase, a commit with any change in the repository.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from py_checks.translations._constants import HOME, SECTION
|
|
12
|
+
from py_checks.translations._errors import TranslationError
|
|
13
|
+
from py_checks.translations._settings import TranslationsSettings
|
|
14
|
+
from py_checks.translations._stamp import fingerprint, stamp, stamped
|
|
15
|
+
from py_checks.translations._tree import dead, selected, source_of, tracked, translation_of
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"HOME",
|
|
19
|
+
"SECTION",
|
|
20
|
+
"TranslationError",
|
|
21
|
+
"TranslationsSettings",
|
|
22
|
+
"dead",
|
|
23
|
+
"fingerprint",
|
|
24
|
+
"selected",
|
|
25
|
+
"source_of",
|
|
26
|
+
"stamp",
|
|
27
|
+
"stamped",
|
|
28
|
+
"tracked",
|
|
29
|
+
"translation_of",
|
|
30
|
+
]
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""Names every module of the package knows."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from typing import Final
|
|
7
|
+
|
|
8
|
+
SECTION: Final = "translations"
|
|
9
|
+
|
|
10
|
+
# Where the languages live, one directory each, mirroring the repository.
|
|
11
|
+
HOME: Final = "docs/langs"
|
|
12
|
+
|
|
13
|
+
# The first line of a translation: the hash of the source it was made from.
|
|
14
|
+
STAMP: Final = "<!-- sha256:{digest} -->"
|
|
15
|
+
STAMPED: Final = re.compile(r"^<!-- sha256:(?P<digest>[0-9a-f]{64}) -->$")
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""The `[translations]` section."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from py_checks.config import CheckSettings
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class TranslationsSettings(CheckSettings):
|
|
9
|
+
"""Which documents are translated, and into what.
|
|
10
|
+
|
|
11
|
+
`langs` — the languages, each a directory under `docs/langs/`.
|
|
12
|
+
`files` — the documents that need a translation, in gitignore syntax: the
|
|
13
|
+
last match wins, and `!` takes a file back out. A directory is excluded
|
|
14
|
+
with what is under it, `!.github/**`; `!.github/` excludes the directory
|
|
15
|
+
itself, and a `*.md` still matches every file inside it.
|
|
16
|
+
|
|
17
|
+
Either one empty, and the rule is silent: which documents a project
|
|
18
|
+
translates, and into what, only the project knows.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
langs: tuple[str, ...] = ()
|
|
22
|
+
files: tuple[str, ...] = ()
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
"""The fingerprint on a translation's first line."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import hashlib
|
|
6
|
+
from typing import TYPE_CHECKING
|
|
7
|
+
|
|
8
|
+
from py_checks.translations._constants import STAMP, STAMPED
|
|
9
|
+
from py_checks.translations._errors import TranslationError
|
|
10
|
+
from py_checks.translations._tree import source_of
|
|
11
|
+
|
|
12
|
+
if TYPE_CHECKING:
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def fingerprint(*, path: Path) -> str:
|
|
17
|
+
"""The SHA-256 of the file's raw bytes.
|
|
18
|
+
|
|
19
|
+
No normalisation: the end-of-file and whitespace hooks keep the bytes
|
|
20
|
+
stable, and a whitespace-only edit that asks for a re-stamp is a cheap
|
|
21
|
+
false alarm.
|
|
22
|
+
"""
|
|
23
|
+
return hashlib.sha256(path.read_bytes()).hexdigest()
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def stamped(*, path: Path) -> str | None:
|
|
27
|
+
"""The digest on the first line; `None` if the first line is not a fingerprint."""
|
|
28
|
+
first = path.read_text(encoding="utf-8").partition("\n")[0]
|
|
29
|
+
found = STAMPED.match(first)
|
|
30
|
+
return None if found is None else found.group("digest")
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def stamp(
|
|
34
|
+
*,
|
|
35
|
+
root: Path,
|
|
36
|
+
translation: str,
|
|
37
|
+
) -> None:
|
|
38
|
+
"""Write or refresh the fingerprint of one translation.
|
|
39
|
+
|
|
40
|
+
It never creates a translation: the translator writes it, then stamps it.
|
|
41
|
+
And it is never part of `run --fix`: a fix that rewrote the hash would
|
|
42
|
+
bless a translation nobody updated, the one thing the check exists to stop.
|
|
43
|
+
"""
|
|
44
|
+
pair = source_of(translation=translation)
|
|
45
|
+
if pair is None:
|
|
46
|
+
message = f"{translation} is not a translation: it lies outside docs/langs/<lang>/"
|
|
47
|
+
raise TranslationError(message)
|
|
48
|
+
path = root / translation
|
|
49
|
+
source = root / pair[1]
|
|
50
|
+
if not path.is_file():
|
|
51
|
+
message = f"{translation} does not exist: write the translation, then stamp it"
|
|
52
|
+
raise TranslationError(message)
|
|
53
|
+
if not source.is_file():
|
|
54
|
+
message = f"{translation} translates nothing: {pair[1]} does not exist"
|
|
55
|
+
raise TranslationError(message)
|
|
56
|
+
text = path.read_text(encoding="utf-8")
|
|
57
|
+
body = text.partition("\n")[2] if stamped(path=path) is not None else text
|
|
58
|
+
line = STAMP.format(digest=fingerprint(path=source))
|
|
59
|
+
path.write_text(f"{line}\n{body}", encoding="utf-8")
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
"""Which files need a translation, and which translation belongs to which file."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import subprocess
|
|
6
|
+
from typing import TYPE_CHECKING, Final
|
|
7
|
+
|
|
8
|
+
from pathspec import GitIgnoreSpec
|
|
9
|
+
|
|
10
|
+
from py_checks.translations._constants import HOME
|
|
11
|
+
from py_checks.translations._errors import TranslationError
|
|
12
|
+
|
|
13
|
+
if TYPE_CHECKING:
|
|
14
|
+
from collections.abc import Iterable
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
|
|
17
|
+
SEPARATOR: Final = "/"
|
|
18
|
+
|
|
19
|
+
# Tracked files and new ones git has not been told to ignore: a document just
|
|
20
|
+
# written is judged before `git add`, and `.venv/` is never a candidate.
|
|
21
|
+
LISTED: Final = ("git", "ls-files", "--cached", "--others", "--exclude-standard", "-z")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def tracked(*, root: Path) -> list[str]:
|
|
25
|
+
"""The repository's files, as paths from its root, that exist on disk.
|
|
26
|
+
|
|
27
|
+
A file deleted but not yet staged is still listed by git; it has nothing
|
|
28
|
+
to translate. A symlink is not a document of its own — `CLAUDE.md` pointing
|
|
29
|
+
at `AGENTS.md` is translated once, as `AGENTS.md`.
|
|
30
|
+
"""
|
|
31
|
+
try:
|
|
32
|
+
finished = subprocess.run( # noqa: S603 — a fixed list of arguments, no shell
|
|
33
|
+
LISTED,
|
|
34
|
+
cwd=root,
|
|
35
|
+
capture_output=True,
|
|
36
|
+
check=True,
|
|
37
|
+
)
|
|
38
|
+
except (OSError, subprocess.CalledProcessError) as error:
|
|
39
|
+
message = f"{root} is not a git repository: translations are matched against its files"
|
|
40
|
+
raise TranslationError(message) from error
|
|
41
|
+
listed = finished.stdout.decode().split("\0")
|
|
42
|
+
return sorted(
|
|
43
|
+
path
|
|
44
|
+
for path in listed
|
|
45
|
+
if path and (root / path).is_file() and not (root / path).is_symlink()
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def selected(
|
|
50
|
+
*,
|
|
51
|
+
paths: Iterable[str],
|
|
52
|
+
files: Iterable[str],
|
|
53
|
+
) -> list[str]:
|
|
54
|
+
"""The sources: the files the patterns select, never a translation itself."""
|
|
55
|
+
spec = GitIgnoreSpec.from_lines(files)
|
|
56
|
+
return [path for path in paths if not _translated(path=path) and spec.match_file(path)]
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def dead(
|
|
60
|
+
*,
|
|
61
|
+
paths: Iterable[str],
|
|
62
|
+
files: tuple[str, ...],
|
|
63
|
+
) -> list[str]:
|
|
64
|
+
"""The patterns that change nothing: without one, the same files are selected.
|
|
65
|
+
|
|
66
|
+
One question covers both mistakes — a pattern that selects nothing, and a
|
|
67
|
+
`!` that excludes nothing, like `!.github/` under a `*.md`.
|
|
68
|
+
"""
|
|
69
|
+
candidates = list(paths)
|
|
70
|
+
whole = selected(
|
|
71
|
+
paths=candidates,
|
|
72
|
+
files=files,
|
|
73
|
+
)
|
|
74
|
+
return [
|
|
75
|
+
pattern
|
|
76
|
+
for index, pattern in enumerate(files)
|
|
77
|
+
if selected(
|
|
78
|
+
paths=candidates,
|
|
79
|
+
files=files[:index] + files[index + 1 :],
|
|
80
|
+
)
|
|
81
|
+
== whole
|
|
82
|
+
]
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def translation_of(
|
|
86
|
+
*,
|
|
87
|
+
source: str,
|
|
88
|
+
lang: str,
|
|
89
|
+
) -> str:
|
|
90
|
+
return f"{HOME}/{lang}/{source}"
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def source_of(*, translation: str) -> tuple[str, str] | None:
|
|
94
|
+
"""The language and the source of a translation; `None` — not one."""
|
|
95
|
+
if not _translated(path=translation):
|
|
96
|
+
return None
|
|
97
|
+
lang, _, source = translation.removeprefix(f"{HOME}/").partition(SEPARATOR)
|
|
98
|
+
if not lang or not source:
|
|
99
|
+
return None
|
|
100
|
+
return lang, source
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _translated(*, path: str) -> bool:
|
|
104
|
+
return path.startswith(f"{HOME}/")
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: python-checks
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.10.0
|
|
4
4
|
Summary: Проверки архитектурных соглашений проекта
|
|
5
5
|
Author: Armontex
|
|
6
6
|
Author-email: Armontex <windle1337@gmail.com>
|
|
7
7
|
License-Expression: MIT
|
|
8
8
|
License-File: LICENSE
|
|
9
9
|
Requires-Dist: libcst>=1.9,<2
|
|
10
|
+
Requires-Dist: pathspec>=1.1,<2
|
|
10
11
|
Requires-Dist: pydantic>=2.13.5,<3
|
|
11
12
|
Requires-Dist: pydantic-settings>=2.15.0,<3
|
|
12
13
|
Requires-Dist: rich>=14.0.0,<16.0.0
|
|
@@ -144,10 +145,10 @@ Twenty-eight rules in nine groups:
|
|
|
144
145
|
| `api` | what an entrance declares about itself |
|
|
145
146
|
| `errors` | the code a refusal carries |
|
|
146
147
|
| `calls` | a function whose call sites can be listed |
|
|
147
|
-
| `hygiene` | a ceiling on a dependency |
|
|
148
|
+
| `hygiene` | a ceiling on a dependency, a translation that kept up |
|
|
148
149
|
|
|
149
150
|
<details>
|
|
150
|
-
<summary>All
|
|
151
|
+
<summary>All thirty</summary>
|
|
151
152
|
|
|
152
153
|
| Code | What fails | Scope |
|
|
153
154
|
|---|---|:-:|
|
|
@@ -180,6 +181,7 @@ Twenty-eight rules in nine groups:
|
|
|
180
181
|
| `refusals` | a no nobody can branch on | file |
|
|
181
182
|
| `confined-functions` | a named function was called from somewhere it may not be | file |
|
|
182
183
|
| `dependency-bounds` | a dependency may move to a version nobody has ever run | project |
|
|
184
|
+
| `translations` | a translated document is missing or no longer matches its source | project |
|
|
183
185
|
|
|
184
186
|
</details>
|
|
185
187
|
|
|
@@ -206,7 +208,7 @@ text("SELECT 1") # db-ok: raw-sql: a liveness probe, there is no ORM form of it
|
|
|
206
208
|
|
|
207
209
|
The canonical form is `# check-ok: <code>: <reason>`, and it lifts exactly one
|
|
208
210
|
rule. Every group has a short word of its own (`# db-ok`, `# type-ok`,
|
|
209
|
-
`# signature-ok`, …): a person remembers the group, not
|
|
211
|
+
`# signature-ok`, …): a person remembers the group, not thirty codes.
|
|
210
212
|
|
|
211
213
|
A line may carry several marks — a signature written in a column gathers them
|
|
212
214
|
on its last line:
|
|
@@ -354,6 +356,7 @@ obeys `ignore`, and is lifted by a mark.
|
|
|
354
356
|
| `py-checks sync [--check]` | build the import contracts and `.env.example` |
|
|
355
357
|
| `py-checks doctor` | check the config itself: typos, dead addresses, rules that say nothing |
|
|
356
358
|
| `py-checks mutation diff\|full\|record` | the mutation gate over `mutmut`; needs `python-checks[mutation]` |
|
|
359
|
+
| `py-checks translations stamp <path>…` | stamp a translation with its source's fingerprint, after translating |
|
|
357
360
|
|
|
358
361
|
## Development
|
|
359
362
|
|
|
@@ -26,9 +26,10 @@ py_checks/checks/effects/_marker.py,sha256=oPi9J1FdKL6gNIC9VNWsifmPEo9l0gqh9TwqC
|
|
|
26
26
|
py_checks/checks/errors/__init__.py,sha256=fO-M5lLR-PPreQrDI91hEi9hQ-tSbqtDt8v6n15i2ic,317
|
|
27
27
|
py_checks/checks/errors/_marker.py,sha256=gbsVYdKuPC0c-z2heKsHLWYMoUj0cibzbpbBhhzL97A,120
|
|
28
28
|
py_checks/checks/errors/_refusals.py,sha256=skmpjjI84XO0Wmd3FsXvgr9825rSmXb62VEOJngL_O8,5637
|
|
29
|
-
py_checks/checks/hygiene/__init__.py,sha256=
|
|
29
|
+
py_checks/checks/hygiene/__init__.py,sha256=IgX492x8c9dZ3sW8q0xffHsQXB4kq1_Cb2J3xKsaTk4,675
|
|
30
30
|
py_checks/checks/hygiene/_dependency_bounds.py,sha256=1vqVfWDi7Q8Ufw02dAyZVbr1WjEqFVF6SqMa_vl0HUs,6811
|
|
31
31
|
py_checks/checks/hygiene/_marker.py,sha256=PLZOPObnGlOEi47rmRolqDKSoPYEbyDAnxHiP8MBlg8,126
|
|
32
|
+
py_checks/checks/hygiene/_translations.py,sha256=-4sDh-Wv8yXChQUaPVkUh_IW_j0ffQDj2aHaf6Y0CbI,5200
|
|
32
33
|
py_checks/checks/imports/__init__.py,sha256=Qr4UTIWJVpr34HTfqqbcw8S0eJ4cAr-XcjF9Jitv1mc,948
|
|
33
34
|
py_checks/checks/imports/_confined.py,sha256=VP5s7H4HVX_Wj5dLUxzLrbse869dpXutZ1i4HHPxnE0,3272
|
|
34
35
|
py_checks/checks/imports/_marker.py,sha256=LNJ1vFrHG2C_3ybl1vJrIx2y9-m7CgTLWG95Z4JXSRM,144
|
|
@@ -58,14 +59,15 @@ py_checks/checks/types/_marker.py,sha256=vj6oymhfDlweuMSAxg7uGpD_ErjBvCy2Fq-g0xA
|
|
|
58
59
|
py_checks/cli/__init__.py,sha256=bSoxcpOM-Gk0XvR-XjKuHvXPwdEeIg0hTjfUL4Ac2WA,290
|
|
59
60
|
py_checks/cli/_app.py,sha256=PAXu38bJN3FJM3GU-geAnFGRrgGc_SUZ3H_CQXmx24I,413
|
|
60
61
|
py_checks/cli/_protocols.py,sha256=NdWZOW5dRvXNAh4VK6hI8A9fy5j2XzxsbPZhAA_-rkw,573
|
|
61
|
-
py_checks/cli/commands/__init__.py,sha256=
|
|
62
|
-
py_checks/cli/commands/_doctor.py,sha256=
|
|
62
|
+
py_checks/cli/commands/__init__.py,sha256=qqyO2gKx1_Ztl-hWJi-ifhj1Wr8VPDtZ-SH1tvmfoco,1085
|
|
63
|
+
py_checks/cli/commands/_doctor.py,sha256=KRVv-Im9CYF_dRPVMuzMJ9Ugcizcn8_fom2Ce7y3V-I,12434
|
|
63
64
|
py_checks/cli/commands/_explain.py,sha256=gT7WR0AIe4BzhmH8BVXUL2ENSvMejh9KT3pctyy-ueQ,2443
|
|
64
65
|
py_checks/cli/commands/_list.py,sha256=PTRpUn_1E6iug_rfoHo6rA6eHtm0-Y6bvjmtVg_6bLY,1516
|
|
65
66
|
py_checks/cli/commands/_mutation.py,sha256=IjMKW7BWa1qDG2Vm2KnhbG-1fF07HRQN8NdKUtKBDd8,6638
|
|
66
67
|
py_checks/cli/commands/_run.py,sha256=y1cJOa56CAfhi1AX4XDlRpRWxiShHvUF4MFWtbLyRBE,4677
|
|
67
68
|
py_checks/cli/commands/_summary.py,sha256=n5wgICfyVpnWTdqn8Vh7NCOzW96IUgAXidDlx5OfS6A,502
|
|
68
69
|
py_checks/cli/commands/_sync.py,sha256=adGo19zSawxLm19p4dIPHiu8P7glmWxPGMtBdaMTVpM,1968
|
|
70
|
+
py_checks/cli/commands/_translations.py,sha256=iICZaSPrg4So6NoER_kA0bZv7Z0EJcZFo4AZF7EKHOc,2545
|
|
69
71
|
py_checks/config/__init__.py,sha256=-CWL1ta7aMNUkfNWn6Bi8LLjAv_vKls_w2zd5seSvJw,1036
|
|
70
72
|
py_checks/config/_base.py,sha256=FTJzmljdwaDvuNQ9kJ7EM6VvkStOItL_RtJbelhPeUw,1154
|
|
71
73
|
py_checks/config/_config.py,sha256=l30K5LzNcn6KRZo109_AhAVrDpcXo0YTdRgB4hLXq5g,4705
|
|
@@ -110,8 +112,14 @@ py_checks/mutation/_settings.py,sha256=HF9-6ICtsHAV8-1MRHDe1wEfj5dbCKux05_YHxl_X
|
|
|
110
112
|
py_checks/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
111
113
|
py_checks/sync/__init__.py,sha256=l5yy0yACEYTnFzR7EXyF7GJ2eX6KZ_dyudxTdKrIUGs,696
|
|
112
114
|
py_checks/sync/_sync.py,sha256=GF1BGkWR_1sP0Lq_XZJ6Lfe59Bm_ABbaWPoeuEWnNrM,1878
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
115
|
+
py_checks/translations/__init__.py,sha256=YUm6LXbM9vJ0SSkeAM9l3lN-ux2qdY0t16HTnJLgVm4,1089
|
|
116
|
+
py_checks/translations/_constants.py,sha256=Fxf8nVBqZHPjttStCLZX1OqwXUHmF165iSCglEFCNDQ,448
|
|
117
|
+
py_checks/translations/_errors.py,sha256=Lwq3kewes4HG8jTv8lnJV8BRzwKBhclKmnxwCkuST5w,180
|
|
118
|
+
py_checks/translations/_settings.py,sha256=LLiDI7IVJGW6R843zVXXYpsbiM_lLYDiHokG4VdFzU4,780
|
|
119
|
+
py_checks/translations/_stamp.py,sha256=3Zdn6o0FF-TZ3NWy3lwu7twsHNIiJ2-TQNDKZ755Ljc,2133
|
|
120
|
+
py_checks/translations/_tree.py,sha256=2ADCmI5RnXcr2erKsw1RRgIa1uKQrF1kn2kAWjB8HY0,3126
|
|
121
|
+
python_checks-0.10.0.dist-info/licenses/LICENSE,sha256=omcAXq_cAQNMI5X3fRdH7UC6W2Zc8AC-G9xIZ2U1xF0,1065
|
|
122
|
+
python_checks-0.10.0.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
|
|
123
|
+
python_checks-0.10.0.dist-info/entry_points.txt,sha256=MZJNsa_rm8J2XSxN1EkS3f6GQh7g6Zgk84iQksy75dw,1768
|
|
124
|
+
python_checks-0.10.0.dist-info/METADATA,sha256=kfyLwPlb1xZXqa4mRJ83LRdLx80-upcbJQJohvQ0ff4,15908
|
|
125
|
+
python_checks-0.10.0.dist-info/RECORD,,
|
|
@@ -31,4 +31,5 @@ schema-drift = py_checks.checks.database:SchemaDrift
|
|
|
31
31
|
sealed-imports = py_checks.checks.imports:SealedImports
|
|
32
32
|
signature-layout = py_checks.checks.signatures:SignatureLayout
|
|
33
33
|
statement-keys = py_checks.checks.database:StatementKeys
|
|
34
|
+
translations = py_checks.checks.hygiene:Translations
|
|
34
35
|
|
|
File without changes
|