python-checks 0.1.0__py3-none-any.whl

py_checks/cli/commands/_explain.py

@@ -0,0 +1,28 @@
+"""Команда `explain`: подробности об одной проверке."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from py_checks.cli.commands._summary import docstring
+from py_checks.core import get
+
+
+def explain(  # check-ok: keyword-only-arguments: подпись команды разбирает typer
+    code: Annotated[str, typer.Argument(help="код проверки")],
+) -> None:
+    """Показать, что проверка требует и какие у неё настройки."""
+    check = get(code=code)
+    console = Console()
+    console.print(docstring(check=check), markup=False)
+    console.print("\nнастройки:", markup=False)
+    for name, field in check.Settings.model_fields.items():
+        key = field.alias or name
+        console.print(f"  {key} = {field.get_default(call_default_factory=True)!r}", markup=False)
+
+
+def register(*, app: typer.Typer) -> None:
+    app.command("explain")(explain)

py_checks/cli/commands/_list.py

@@ -0,0 +1,62 @@
+"""Команда `list`: какие проверки есть."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.table import Table
+
+from py_checks.cli.commands._summary import summary
+from py_checks.config import find_root, load
+from py_checks.core import Scope, available
+
+if TYPE_CHECKING:
+    import typer
+
+    from py_checks.config import Config
+    from py_checks.core import Check
+
+
+def list_checks() -> None:
+    """Показать все проверки: код, состояние и одну строку описания."""
+    config = load(root=find_root(start=Path.cwd()))
+    table = Table(
+        box=None,
+        pad_edge=False,
+    )
+    table.add_column("код")
+    table.add_column("состояние")
+    table.add_column("что делает")
+    for code, check in sorted(available().listed.items()):
+        table.add_row(
+            code,
+            _state(
+                check=check,
+                config=config,
+            ),
+            summary(check=check),
+        )
+    Console().print(table)
+
+
+def _state(
+    *,
+    check: Check,
+    config: Config,
+) -> str:
+    """Включено, выключено — или включено, но не в обычном прогоне.
+
+    Правилу, которому нужна живая среда, место в CI, поэтому вместо «вкл» в
+    таблице стоит то, чем его зовут.
+    """
+    if not config.enabled(code=check.code):
+        return "выкл"
+    if check.scope is Scope.ENVIRONMENT:
+        return "--all"
+    return "вкл"
+
+
+def register(*, app: typer.Typer) -> None:
+    app.command("list")(list_checks)

py_checks/cli/commands/_run.py

@@ -0,0 +1,167 @@
+"""Команда `run`: прогнать проверки."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+
+from py_checks.config import Config, find_root, load
+from py_checks.core import (
+    Checks,
+    Scope,
+    UnknownCheckError,
+    Violation,
+    available,
+    fix,
+    get,
+    python_files,
+    reformat,
+    report,
+    survey,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from py_checks.core import Check
+
+
+def run(  # check-ok: keyword-only-arguments: подпись команды разбирает typer
+    paths: Annotated[
+        list[Path] | None,
+        typer.Argument(help="файлы или папки; без них — весь `src` проекта"),
+    ] = None,
+    select: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--select",
+            "-s",
+            help="коды проверок через запятую; без них — все включённые",
+        ),
+    ] = None,
+    autofix: Annotated[
+        bool,
+        typer.Option("--fix", help="исправить то, что правится само"),
+    ] = False,
+    everything: Annotated[
+        bool,
+        typer.Option("--all", help="вместе с правилами, которым нужна живая среда"),
+    ] = False,
+) -> None:
+    """Проверить файлы и вернуть код выхода: 0 — чисто, 1 — есть нарушения."""
+    root = find_root(start=Path.cwd())
+    config = load(root=root)
+    chosen = _chosen(
+        select=select,
+        config=config,
+        paths=bool(paths),
+        everything=everything,
+    )
+    # Обход дерева нужен только файловым правилам: прогон одного правила про
+    # проект не должен читать список из тысячи файлов, чтобы никому его не дать.
+    files = (
+        python_files(
+            paths=paths or [],
+            root=root,
+            default=root / config.src,
+            exclude=config.excluded,
+        )
+        if chosen.files
+        else []
+    )
+    violations = survey(
+        chosen=chosen,
+        files=files,
+        config=config,
+        root=root,
+    )
+    if autofix:
+        violations = _fixed(violations=violations)
+    raise typer.Exit(
+        report(
+            violations=violations,
+            root=root,
+            checked=len(files),
+        )
+    )
+
+
+def _fixed(*, violations: list[Violation]) -> list[Violation]:
+    """Наложить правки и вернуть то, что осталось человеку."""
+    changed, left = fix(violations=violations)
+    reformat(paths=changed)
+    return left
+
+
+def _chosen(
+    *,
+    select: list[str] | None,
+    config: Config,
+    paths: bool,
+    everything: bool,
+) -> Checks:
+    """Выбранные проверки, а без выбора — все, кроме отключённых в конфиге.
+
+    Явный `--select` сильнее всего остального: если проверку позвали по имени,
+    значит её хотят запустить именно сейчас — и несмотря на `ignore`, и
+    несмотря на то, что ей нужна база.
+    """
+    listed = available()
+    if select:
+        return listed.only(codes=_codes(select=select))
+    return listed.only(
+        codes={
+            code
+            for code, check in listed.listed.items()
+            if config.enabled(code=code)
+            and _wanted(
+                check=check,
+                paths=paths,
+                everything=everything,
+            )
+        }
+    )
+
+
+def _codes(*, select: Sequence[str]) -> set[str]:
+    """Коды из `--select`: и повторённый флаг, и список через запятую.
+
+    Набор правил пишут в одну строку — `-s raw-sql,statement-keys`, — потому
+    что так его и держат в голове: не по одному флагу на правило, а списком.
+    Повторённый флаг остаётся рабочим, оба способа дают одно и то же.
+
+    Опечатка в коде — ошибка разбора аргумента, а не падение: имя проверки
+    приходит из командной строки, и отвечать на него следом трассировкой
+    значит показывать внутренности там, где ошибся человек.
+    """
+    named = (code.strip() for value in select for code in value.split(","))
+    try:
+        return {get(code=code).code for code in named if code}
+    except UnknownCheckError as error:
+        raise typer.BadParameter(str(error), param_hint="--select") from error
+
+
+def _wanted(
+    *,
+    check: Check,
+    paths: bool,
+    everything: bool,
+) -> bool:
+    """Входит ли правило в прогон, которому не назвали имён.
+
+    Названные пути правил про проект не касаются: прогон по одному файлу
+    проверяет этот файл, а не проект вокруг него. Правилу, которому нужна
+    живая среда, место в CI, а не в хуке на коммит, — его зовут `--all` или по
+    имени.
+    """
+    if paths and check.scope is not Scope.FILE:
+        return False
+    if check.scope is Scope.ENVIRONMENT:
+        return everything
+    return True
+
+
+def register(*, app: typer.Typer) -> None:
+    app.command("run")(run)

py_checks/cli/commands/_summary.py

@@ -0,0 +1,20 @@
+"""Описание проверки, взятое из её докстринга."""
+
+from __future__ import annotations
+
+import inspect as introspect
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from py_checks.core import Check
+
+NO_DOC: Final = "нет описания"
+
+
+def docstring(*, check: Check) -> str:
+    return introspect.getdoc(type(check)) or NO_DOC
+
+
+def summary(*, check: Check) -> str:
+    """Первая строка докстринга: правило одной фразой."""
+    return docstring(check=check).splitlines()[0]

py_checks/cli/commands/_sync.py

@@ -0,0 +1,80 @@
+"""Команда `sync`: собрать конфиги, которые зависят от раскладки проекта."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from rich.console import Console
+
+from py_checks.config import find_root
+from py_checks.core import EXIT_OK, EXIT_VIOLATION
+from py_checks.sync import stale, write
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def sync(  # check-ok: keyword-only-arguments: подпись команды разбирает typer
+    check: Annotated[
+        bool,
+        typer.Option("--check", help="ничего не писать, только сказать, что устарело"),
+    ] = False,
+) -> None:
+    """Собрать файлы, которые выводятся из кода: контракты импортов и `.env.example`."""
+    root = find_root(start=Path.cwd())
+    console = Console(
+        stderr=True,
+        soft_wrap=True,
+    )
+    if check:
+        raise typer.Exit(
+            _report(
+                stale=stale(root=root),
+                console=console,
+            )
+        )
+    for path in write(root=root):
+        _say(
+            text=f"собран {path.relative_to(root)}",
+            console=console,
+        )
+    raise typer.Exit(EXIT_OK)
+
+
+def _report(
+    *,
+    stale: Sequence[Path],
+    console: Console,
+) -> int:
+    """Собранный файл отстал от того, что объявлено в настройках или лежит на диске."""
+    for path in stale:
+        _say(
+            text=f"{path}: устарел, запусти `py-checks sync`",
+            console=console,
+        )
+    if stale:
+        return EXIT_VIOLATION
+    _say(
+        text="ok: собранные файлы совпадают с кодом и настройками",
+        console=console,
+    )
+    return EXIT_OK
+
+
+def _say(
+    *,
+    text: str,
+    console: Console,
+) -> None:
+    """Печатать как есть: в строке бывают пути и секции, разметка тут лишняя."""
+    console.print(
+        text,
+        markup=False,
+        highlight=False,
+    )
+
+
+def register(*, app: typer.Typer) -> None:
+    app.command("sync")(sync)

py_checks/config/__init__.py

@@ -0,0 +1,31 @@
+"""Настройки из `pyproject.toml` проекта.
+
+Настройки живут либо в своём файле — `py-checks.toml` или `pychecks.toml`,
+с точкой в начале или без, — либо секцией `[tool.py-checks]` в
+`pyproject.toml`. В своём
+файле приставки нет: весь файл и есть эта секция. Внутри — по секции на
+проверку, и каждая описана моделью pydantic, поэтому опечатка в названии
+настройки падает сразу и с понятным текстом.
+"""
+
+from py_checks.config._base import CheckSettings
+from py_checks.config._config import Config, prefix
+from py_checks.config._constants import DEFAULT_EXCLUDE, PYPROJECT, SECTION, STANDALONE
+from py_checks.config._errors import ConfigError
+from py_checks.config._loader import find_root, load
+from py_checks.config._toml import TomlTable, TomlValue
+
+__all__ = [
+    "DEFAULT_EXCLUDE",
+    "PYPROJECT",
+    "SECTION",
+    "STANDALONE",
+    "CheckSettings",
+    "Config",
+    "ConfigError",
+    "TomlTable",
+    "TomlValue",
+    "find_root",
+    "load",
+    "prefix",
+]

py_checks/config/_base.py

@@ -0,0 +1,26 @@
+"""Базовая модель настроек проверки."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+def _to_kebab(name: str) -> str:  # check-ok: keyword-only-arguments: pydantic зовёт по позиции
+    return name.replace("_", "-")
+
+
+class CheckSettings(BaseModel):
+    """Настройки одной проверки из её секции в `pyproject.toml`.
+
+    В файле ключи пишутся через дефис (`max-lines`), в коде — через
+    подчёркивание. `extra="forbid"` нужен, чтобы опечатка падала сразу: молча
+    проигнорированная настройка — это проверка, которая работает не так, как
+    написано в конфиге, и никто об этом не знает.
+    """
+
+    model_config = ConfigDict(
+        alias_generator=_to_kebab,
+        populate_by_name=True,
+        extra="forbid",
+        frozen=True,
+    )

py_checks/config/_config.py

@@ -0,0 +1,76 @@
+"""Общие настройки проекта."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field, ValidationError
+
+from py_checks.config._base import CheckSettings
+from py_checks.config._constants import DEFAULT_EXCLUDE, PYPROJECT, SECTION
+from py_checks.config._errors import ConfigError
+from py_checks.config._toml import TomlTable
+
+
+def prefix(*, source: Path | None) -> str:
+    """Как называется секция проверки в том файле, откуда пришли настройки.
+
+    В `pyproject.toml` инструменты живут под своей приставкой, потому что файл
+    общий; в своём файле приставки нет — весь файл принадлежит одному
+    инструменту. Сообщение об ошибке обязано звать секцию так, как её и правда
+    зовут в этом файле: иначе оно посылает читателя не туда.
+    """
+    if source is None or source.name == PYPROJECT:
+        return f"tool.{SECTION}."
+    return ""
+
+
+class Config(CheckSettings):
+    """Где искать код и что не проверять.
+
+    Настройки самих проверок сюда не попадают: они лежат в своих секциях и
+    разбираются моделью той проверки, которой принадлежат. Ядро держит их
+    нетронутыми в `checks` и отдаёт владельцу через `settings_for`.
+    """
+
+    src: Path = Path("src")
+    exclude: tuple[str, ...] = DEFAULT_EXCLUDE
+    extend_exclude: tuple[str, ...] = ()
+    ignore: tuple[str, ...] = ()
+    checks: dict[str, TomlTable] = Field(
+        default_factory=dict,
+        exclude=True,
+    )
+    # Файл, из которого настройки прочитаны: он же и место, куда сообщение об
+    # ошибке отправляет читателя.
+    origin: Path | None = Field(
+        default=None,
+        exclude=True,
+    )
+
+    @property
+    def excluded(self) -> tuple[str, ...]:
+        """Что не проверяем: список по умолчанию плюс добавленный проектом.
+
+        `exclude` задаёт весь список целиком, `extend-exclude` добавляет к нему:
+        так проект добавляет свою папку, не переписывая `.venv` и остальное.
+        """
+        return self.exclude + self.extend_exclude
+
+    def section(self, *, code: str) -> TomlTable:
+        return self.checks.get(code, {})
+
+    def settings_for(
+        self,
+        *,
+        code: str,
+        model: type[CheckSettings],
+    ) -> CheckSettings:
+        """Настройки проверки: её секция, проверенная её же моделью."""
+        try:
+            return model.model_validate(self.section(code=code))
+        except ValidationError as error:
+            raise ConfigError(f"[{prefix(source=self.origin)}{code}]: {error}") from error
+
+    def enabled(self, *, code: str) -> bool:
+        return code not in self.ignore

py_checks/config/_constants.py

@@ -0,0 +1,31 @@
+"""Имена и значения по умолчанию, общие для всего чтения настроек."""
+
+from __future__ import annotations
+
+from typing import Final
+
+PYPROJECT: Final = "pyproject.toml"
+
+SECTION: Final = "py-checks"
+
+# Свой файл настроек — как у ruff и mypy: назван именем инструмента, с точкой
+# в начале и без. В нём приставки `[tool.py-checks]` нет: весь файл и есть
+# эта секция, а `[<код>]` в нём — секция проверки.
+#
+# Имён четыре: полное и короткое, каждое с точкой и без. Угадывать, как проект
+# назовёт свой файл, дешевле, чем отказывать ему за не ту букву, — а лежать
+# сразу двум файлам всё равно запрещено.
+STANDALONE: Final[tuple[str, ...]] = (
+    ".py-checks.toml",
+    "py-checks.toml",
+    ".pychecks.toml",
+    "pychecks.toml",
+)
+
+DEFAULT_EXCLUDE: Final[tuple[str, ...]] = (
+    ".venv/*",
+    "build/*",
+    "dist/*",
+    "**/__pycache__/*",
+    "**/migrations/versions/*",
+)

py_checks/config/_errors.py

@@ -0,0 +1,12 @@
+"""Ошибки чтения настроек."""
+
+from __future__ import annotations
+
+
+class ConfigError(Exception):
+    """Конфиг есть, но прочитать его нельзя.
+
+    Одна ошибка на все случаи: битый TOML, неизвестный ключ, неверное значение.
+    Для того, кто запустил проверку, это одно и то же событие — конфиг надо
+    починить, — а подробности несёт текст.
+    """

py_checks/config/_loader.py

@@ -0,0 +1,133 @@
+"""Чтение настроек: из своего файла проекта или из `pyproject.toml`."""
+
+from __future__ import annotations
+
+import tomllib
+from typing import TYPE_CHECKING, Final
+
+from pydantic import ValidationError
+
+from py_checks.config._config import Config, prefix
+from py_checks.config._constants import PYPROJECT, SECTION, STANDALONE
+from py_checks.config._errors import ConfigError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from py_checks.config._toml import TomlTable, TomlValue
+
+# Все файлы, по которым узнаётся корень проекта. `pyproject.toml` последний:
+# он у проекта есть почти всегда, а свой файл настроек лежит рядом с ним.
+ANCHORS: Final[tuple[str, ...]] = (*STANDALONE, PYPROJECT)
+
+
+def find_root(*, start: Path) -> Path:
+    """Ближайшая папка вверх по дереву, где лежит манифест или свой файл настроек.
+
+    Именно она считается корнем проекта: пути в конфиге и в выводе даются
+    относительно неё, чтобы строка нарушения не зависела от того, откуда
+    запустили проверку.
+    """
+    for directory in (start, *start.parents):
+        if any((directory / name).is_file() for name in ANCHORS):
+            return directory
+    return start
+
+
+def load(*, root: Path) -> Config:
+    """Настройки проекта; если их нигде нет — значения по умолчанию.
+
+    Настройки живут либо в своём файле — `py-checks.toml` или
+    `pychecks.toml`, с точкой в начале или без, — либо секцией
+    `[tool.py-checks]` в `pyproject.toml`. В своём файле приставки нет:
+    весь файл и есть эта секция.
+
+    Двух мест разом не бывает: это не слияние, а вопрос без ответа, и лучше
+    спросить его вслух, чем молча прочитать одно и забыть про другое.
+    """
+    found = _found(root=root)
+    if not found:
+        return Config()
+    if len(found) > 1:
+        raise ConfigError(
+            "настройки лежат в нескольких местах: "
+            + ", ".join(source.name for source, _ in found)
+            + "; оставь одно, иначе неизвестно, какое из них читают"
+        )
+    source, section = found[0]
+    return _build(
+        section=section,
+        source=source,
+    )
+
+
+def _found(*, root: Path) -> list[tuple[Path, TomlTable]]:
+    """Файлы, в которых настройки этого инструмента действительно есть.
+
+    `pyproject.toml` без секции файлом настроек не считается: он лежит у
+    каждого проекта, и молчаливое присутствие — не выбор автора.
+    """
+    found: list[tuple[Path, TomlTable]] = []
+    for name in STANDALONE:
+        path = root / name
+        if path.is_file():
+            found.append((path, _document(path=path)))
+    pyproject = root / PYPROJECT
+    if pyproject.is_file() and (section := _section(document=_document(path=pyproject))):
+        found.append((pyproject, section))
+    return found
+
+
+def _document(*, path: Path) -> TomlTable:
+    try:
+        return tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigError(f"{path}: {error}") from error
+
+
+def _section(*, document: TomlTable) -> TomlTable:
+    tool = document.get("tool")
+    section = tool.get(SECTION) if isinstance(tool, dict) else None
+    return section if isinstance(section, dict) else {}
+
+
+def _build(
+    *,
+    section: TomlTable,
+    source: Path,
+) -> Config:
+    own, checks = _split(section=section)
+    named = prefix(source=source)
+    # В своём файле секции нет — называть в сообщении нечего, кроме файла.
+    where = f" [{named.rstrip('.')}]" if named else ""
+    try:
+        return Config.model_validate({**own, "checks": checks, "origin": source})
+    except ValidationError as error:
+        raise ConfigError(f"{source}{where}: {error}") from error
+
+
+def _split(*, section: TomlTable) -> tuple[TomlTable, dict[str, TomlTable]]:
+    """Свои ключи отдельно, вложенные таблицы проверок отдельно."""
+    own: TomlTable = {}
+    checks: dict[str, TomlTable] = {}
+    for key, value in section.items():
+        _place(
+            key=key,
+            value=value,
+            own=own,
+            checks=checks,
+        )
+    return own, checks
+
+
+def _place(
+    *,
+    key: str,
+    value: TomlValue,
+    own: TomlTable,
+    checks: dict[str, TomlTable],
+) -> None:
+    if isinstance(value, dict):
+        checks[key] = value
+    else:
+        own[key] = value