python-checks 0.1.0__py3-none-any.whl

py_checks/core/_settings.py

@@ -0,0 +1,44 @@
+"""Сужение настроек до модели конкретной проверки."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from py_checks.config import CheckSettings
+
+
+class SettingsMismatchError(Exception):
+    """Проверке отдали не её настройки."""
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        expected: type[object],
+        got: type[object],
+    ) -> None:
+        super().__init__(f"{code}: ожидались {expected.__name__}, пришли {got.__name__}")
+        self.code = code
+
+
+def settings_as[S: CheckSettings](
+    *,
+    settings: CheckSettings,
+    model: type[S],
+    code: str,
+) -> S:
+    """Те же настройки, но уже своего типа.
+
+    Ядро отдаёт проверке общий `CheckSettings`: иначе протокол пришлось бы
+    параметризовать типом настроек, и реестр перестал бы складываться в один
+    словарь. Сужение здесь — одна строка в начале правила, зато дальше поля
+    видит и редактор, и pyright.
+    """
+    if not isinstance(settings, model):
+        raise SettingsMismatchError(
+            code=code,
+            expected=model,
+            got=type(settings),
+        )
+    return settings

py_checks/core/_source.py

@@ -0,0 +1,94 @@
+"""Разобранный файл, который получают проверки."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+import libcst
+
+from py_checks.core._errors import ParseError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ParsedFile:
+    """Файл, прочитанный один раз и разобранный не больше одного раза.
+
+    Дерево строится лениво и запоминается: проверок на файл много, а разбор
+    один. Файлам, которым дерево не нужно (длина модуля, например), платить за
+    него не приходится.
+
+    Деревьев два, и оба ленивые. `tree` — обычный `ast`: быстрый, его хватает,
+    когда правило только смотрит. `module` — дерево `libcst`, в котором есть
+    комментарии, кавычки и пробелы: такое дерево можно переписать и отдать
+    обратно текстом, ничего чужого не потеряв. Правило берёт то, что ему нужно,
+    и за второй разбор платит только оно.
+    """
+
+    __slots__ = ("_lines", "_module", "_text", "_tree", "path", "source")
+
+    def __init__(
+        self,
+        *,
+        path: Path,
+        text: str,
+        source: Path | None = None,
+    ) -> None:
+        self.path = path
+        # Корень исходников проекта: по нему правила, которые говорят о месте
+        # («ORM живёт в `infra/database`»), считают адрес файла. Угадывать его
+        # по `__init__.py` нельзя — папка без него встречается и внутри пакета.
+        self.source = source
+        self._text = text
+        self._tree: ast.Module | None = None
+        self._module: libcst.Module | None = None
+        self._lines: tuple[str, ...] | None = None
+
+    @classmethod
+    def from_path(
+        cls,
+        *,
+        path: Path,
+        source: Path | None = None,
+    ) -> ParsedFile:
+        return cls(
+            path=path,
+            text=path.read_text(encoding="utf-8"),
+            source=source,
+        )
+
+    @property
+    def text(self) -> str:
+        return self._text
+
+    @property
+    def lines(self) -> tuple[str, ...]:
+        if self._lines is None:
+            self._lines = tuple(self._text.splitlines())
+        return self._lines
+
+    @property
+    def tree(self) -> ast.Module:
+        if self._tree is None:
+            try:
+                self._tree = ast.parse(self._text, filename=str(self.path))
+            except SyntaxError as error:
+                raise ParseError(
+                    path=self.path,
+                    error=error,
+                ) from error
+        return self._tree
+
+    @property
+    def module(self) -> libcst.Module:
+        if self._module is None:
+            try:
+                self._module = libcst.parse_module(self._text)
+            except libcst.ParserSyntaxError as error:
+                raise ParseError(
+                    path=self.path,
+                    error=SyntaxError(error.message),
+                ) from error
+        return self._module

py_checks/core/_violation.py

@@ -0,0 +1,73 @@
+"""Нарушение и то, как оно выглядит в выводе."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import ast
+    from pathlib import Path
+
+    from py_checks.core._edit import Edit
+
+
+@dataclass(frozen=True, slots=True)
+class Violation:
+    """Одно нарушение: где, чем и почему.
+
+    Строка и колонка нумеруются с единицы, как их показывает редактор. У `ast`
+    колонка начинается с нуля, поэтому узлы дерева превращаются в нарушение
+    через `from_node`, а не вручную.
+
+    `end_line` нужен только тем нарушениям, которые занимают несколько строк:
+    по нему ядро ищет маркер во всей подписи, а не в одной её первой строке.
+
+    `edit` есть у нарушения, которое правило умеет исправить. Правку несёт само
+    нарушение, а не отдельный проход: тот, кто нашёл место, знает о нём больше
+    всех, и второй раз разбирать файл ради починки незачем.
+    """
+
+    path: Path
+    line: int
+    column: int
+    code: str
+    message: str
+    end_line: int | None = None
+    edit: Edit | None = None
+
+    @classmethod
+    def from_node(
+        cls,
+        *,
+        node: ast.AST,
+        path: Path,
+        code: str,
+        message: str,
+        end_line: int | None = None,
+        edit: Edit | None = None,
+    ) -> Violation:
+        line = getattr(node, "lineno", 1)
+        column = getattr(node, "col_offset", 0)
+        return cls(
+            path=path,
+            line=line,
+            column=column + 1,
+            code=code,
+            message=message,
+            end_line=end_line,
+            edit=edit,
+        )
+
+    def render(self, *, root: Path | None = None) -> str:
+        """`путь:строка:колонка: код: сообщение`.
+
+        Формат выбран не ради красоты: по нему строку понимают редактор, `grep`
+        и CI, и по ней можно перейти к месту одним щелчком.
+        """
+        path = self.path
+        if root is not None:
+            with suppress(ValueError):
+                path = path.relative_to(root)
+        return f"{path}:{self.line}:{self.column}: {self.code}: {self.message}"

py_checks/environment/__init__.py

@@ -0,0 +1,14 @@
+"""Пример файла окружения, собранный из классов настроек проекта.
+
+Имя переменной знает поле — оно объявляет его `validation_alias`, и правило
+`config-fields` за этим следит. Значит, список переменных выводится из тех же
+классов, что их читают, и файл, который его перечисляет, нет смысла вести
+рукой: он расходится молча, а замечают это, когда переменной не оказалось на
+проде.
+"""
+
+from py_checks.environment._constants import FILE, SECTION
+from py_checks.environment._render import render
+from py_checks.environment._settings import Example, example
+
+__all__ = ["FILE", "SECTION", "Example", "example", "render"]

py_checks/environment/_constants.py

@@ -0,0 +1,9 @@
+"""Имена, о которых знают все модули пакета."""
+
+from __future__ import annotations
+
+from typing import Final
+
+SECTION: Final = "env-example"
+
+FILE: Final = ".env.example"

py_checks/environment/_render.py

@@ -0,0 +1,227 @@
+"""Сборка `.env.example` из классов настроек проекта."""
+
+from __future__ import annotations
+
+import enum
+import importlib
+import json
+import sys
+from pathlib import Path
+from textwrap import wrap
+from typing import TYPE_CHECKING, Any, Final
+
+from pydantic import BaseModel, SecretStr
+from pydantic_core import PydanticUndefined
+
+from py_checks.config import ConfigError, prefix
+from py_checks.environment._constants import SECTION
+from py_checks.environment._settings import example
+
+if TYPE_CHECKING:
+    from pydantic.fields import FieldInfo
+
+    from py_checks.config import Config
+
+HEADER: Final = """\
+# Переменные окружения, которые читает сервис. Файл собирает `py-checks sync`
+# из классов настроек, перечисленных в [{section}] — править его нечего,
+# следующий sync перезапишет. Значение по умолчанию здесь для того, чтобы его
+# было видно, а не потому, что переменную обязательно задавать.
+"""
+
+SEPARATOR: Final = ":"
+
+# Ширина комментария: та же, по которой переносят текст в самих докстрингах.
+WIDTH: Final = 77
+
+
+def render(
+    *,
+    root: Path,
+    config: Config,
+) -> tuple[Path, str] | None:
+    """Путь и текст файла; `None`, если проект не объявил ни одного класса."""
+    declared = example(config=config)
+    if not declared.settings:
+        return None
+    blocks = [
+        block
+        for name in declared.settings
+        for block in _blocks(
+            model=_imported(
+                path=name,
+                root=root,
+                src=config.src,
+            ),
+            seen=set(),
+        )
+    ]
+    return root / declared.path, "\n".join(
+        [
+            HEADER.format(section=f"{prefix(source=config.origin)}{SECTION}"),
+            *blocks,
+        ]
+    )
+
+
+def _imported(
+    *,
+    path: str,
+    root: Path,
+    src: Path,
+) -> type[BaseModel]:
+    """Класс настроек по записи `модуль:Класс`.
+
+    Импорт, а не чтение исходника: имя переменной — значение атрибута поля, и
+    собрано оно вызовом (`AliasChoices(...)`, имя, посчитанное при создании
+    класса). Прочитать его текстом значит выполнить этот вызов самому.
+    """
+    module, _, attribute = path.partition(SEPARATOR)
+    if not attribute:
+        message = f"[{SECTION}]: {path!r} — нужна запись вида `модуль:Класс`"
+        raise ConfigError(message)
+    _reachable(
+        root=root,
+        src=src,
+    )
+    try:
+        found = getattr(importlib.import_module(module), attribute)
+    except (ImportError, AttributeError) as error:
+        raise ConfigError(f"[{SECTION}]: {path!r} не импортируется: {error}") from error
+    if not (isinstance(found, type) and issubclass(found, BaseModel)):
+        message = f"[{SECTION}]: {path!r} — не модель pydantic"
+        raise ConfigError(message)
+    return found
+
+
+def _reachable(
+    *,
+    root: Path,
+    src: Path,
+) -> None:
+    """Дать импорту найти пакет проекта, даже если проект не установлен."""
+    for directory in (root / src, root):
+        name = str(directory)
+        if directory.is_dir() and name not in sys.path:
+            sys.path.insert(0, name)
+
+
+def _blocks(
+    *,
+    model: type[BaseModel],
+    seen: set[type[BaseModel]],
+) -> list[str]:
+    """Класс и вложенные в него секции, каждая своим куском.
+
+    Проекту хватает назвать корневой класс: секции он и так перечислил — в
+    собственных полях, — и повторять их список в настройках значит завести
+    второй, который разойдётся с первым.
+    """
+    if model in seen:
+        return []
+    seen.add(model)
+    lines = [f"# --- {_origin(model=model)} ---", *_commented(text=_said(model=model))]
+    nested: list[str] = []
+    for field in model.model_fields.values():
+        section = _section(field=field)
+        if section is not None:
+            nested.extend(
+                _blocks(
+                    model=section,
+                    seen=seen,
+                )
+            )
+            continue
+        name = _variable(field=field)
+        if name is None:
+            continue
+        lines.extend(_commented(text=field.description))
+        lines.append(f"{name}={_value(field=field)}")
+    # Корень, у которого своих переменных нет, в файл не едет: заголовок с
+    # докстрингом и пустотой под ним ничего не сообщает.
+    own = [] if len(lines) == 1 or not _variables(lines=lines) else ["\n".join(lines) + "\n"]
+    return own + nested
+
+
+def _variables(*, lines: list[str]) -> bool:
+    """Есть ли в куске хоть одна переменная, а не одни комментарии."""
+    return any(not line.startswith("#") for line in lines)
+
+
+def _origin(*, model: type[BaseModel]) -> str:
+    """Как класс записывают в настройках: `модуль:Класс`."""
+    return f"{model.__module__}{SEPARATOR}{model.__qualname__}"
+
+
+def _section(*, field: FieldInfo) -> type[BaseModel] | None:
+    """Вложенная секция настроек, если поле — она.
+
+    Секция узнаётся по типу поля: `default_factory` бывает и у обычного
+    значения, а модель в аннотации — это ровно «здесь начинается ещё одна
+    группа переменных».
+    """
+    annotation = field.annotation
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+    return None
+
+
+def _said(*, model: type[BaseModel]) -> str | None:
+    """Первый абзац докстринга класса: чем эта секция занимается.
+
+    Абзац, а не строка: докстринг переносят по ширине файла, и первая строка
+    обрывается на середине фразы.
+    """
+    if model.__doc__ is None:
+        return None
+    paragraph = model.__doc__.strip().split("\n\n", maxsplit=1)[0]
+    return " ".join(paragraph.split()) or None
+
+
+def _commented(*, text: str | None) -> list[str]:
+    """Текст как комментарий, разложенный по ширине строки."""
+    if not text:
+        return []
+    return [f"# {line}" for line in wrap(text, width=WIDTH)]
+
+
+def _variable(*, field: FieldInfo) -> str | None:
+    """Имя переменной, которую читает поле; `None` — если поле не переменная.
+
+    Поле, собранное фабрикой, — вложенная секция: переменные читают её
+    собственные поля, а у неё самой их нет.
+    """
+    if field.default_factory is not None:
+        return None
+    alias = field.validation_alias
+    if isinstance(alias, str):
+        return alias
+    choices = getattr(alias, "choices", ())
+    named = [choice for choice in choices if isinstance(choice, str)]
+    return named[0] if named else None
+
+
+def _value(*, field: FieldInfo) -> str:
+    """Значение по умолчанию так, как его пишут в файле окружения."""
+    default = field.default
+    if default is PydanticUndefined or default is None:
+        return ""
+    return _written(value=default)
+
+
+def _written(*, value: Any) -> str:
+    if isinstance(value, SecretStr):
+        return value.get_secret_value()
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, enum.Enum):
+        return _written(value=value.value)
+    if isinstance(value, (str, int, float, Path)):
+        return str(value)
+    # Составное значение pydantic-settings читает как JSON, а не как строку:
+    # список, записанный через запятую, он в поле не превратит.
+    return json.dumps(
+        value,
+        default=str,
+        ensure_ascii=False,
+    )

py_checks/environment/_settings.py

@@ -0,0 +1,35 @@
+"""Классы настроек, из которых собирается пример окружения."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import ValidationError
+
+from py_checks.config import CheckSettings, ConfigError, prefix
+from py_checks.environment._constants import FILE, SECTION
+
+if TYPE_CHECKING:
+    from py_checks.config import Config
+
+
+class Example(CheckSettings):
+    """Секция `[tool.py-checks.env-example]`.
+
+    `settings` — классы настроек, каждый как `модуль:Класс`. Перечисляются
+    именно секции, а не один корневой класс: корень собирает их фабриками, и
+    его собственные поля — это секции, а не переменные. Пустой список значит
+    «ничего не собирать»: проект без настроек из окружения — обычное дело.
+
+    `path` — куда писать; по умолчанию `.env.example` в корне.
+    """
+
+    settings: tuple[str, ...] = ()
+    path: str = FILE
+
+
+def example(*, config: Config) -> Example:
+    try:
+        return Example.model_validate(config.section(code=SECTION))
+    except ValidationError as error:
+        raise ConfigError(f"[{prefix(source=config.origin)}{SECTION}]: {error}") from error

py_checks/sync/__init__.py

@@ -0,0 +1,16 @@
+"""Файлы, которые библиотека собирает для проекта.
+
+Сегодня их два: контракты импортов для import-linter и `.env.example`.
+Настройки ruff, pyright и остальных инструментов библиотека не трогает: их
+приносит шаблон, и дальше они принадлежат проекту, который правит их как
+считает нужным.
+
+Собирается то, что нельзя написать один раз: слой, которого нет на диске,
+ломает весь прогон import-linter, а раскладка за жизнь проекта меняется;
+список переменных живёт в полях классов настроек, и файл, который ведут рядом
+руками, расходится с ними молча.
+"""
+
+from py_checks.sync._sync import planned, stale, write
+
+__all__ = ["planned", "stale", "write"]

py_checks/sync/_sync.py

@@ -0,0 +1,60 @@
+"""Конфиги, которые собирает библиотека."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from py_checks.config import load
+from py_checks.contracts import FILE, render
+from py_checks.environment import render as environment
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def planned(*, root: Path) -> dict[Path, str]:
+    """Что библиотека собирает для этого проекта.
+
+    Настройки ruff, pyright и прочих инструментов сюда не входят: их приносит
+    шаблон, и дальше это файлы проекта. Собирается то, что обязано совпадать с
+    кодом и расходится молча: контракты импортов — с раскладкой на диске (слой,
+    которого нет, роняет весь прогон import-linter), `.env.example` — с полями
+    классов настроек (переменная, которой нет в файле, обнаруживается на проде).
+    """
+    config = load(root=root)
+    built: dict[Path, str] = {}
+    contracts = render(
+        root=root,
+        config=config,
+    )
+    if contracts is not None:
+        built[root / FILE] = contracts
+    variables = environment(
+        root=root,
+        config=config,
+    )
+    if variables is not None:
+        path, text = variables
+        built[path] = text
+    return built
+
+
+def stale(*, root: Path) -> list[Path]:
+    """Файлы, которые разошлись с тем, что собралось бы сейчас."""
+    return [path for path, text in planned(root=root).items() if _read(path=path) != text]
+
+
+def write(*, root: Path) -> list[Path]:
+    """Собрать заново; вернуть то, что изменилось."""
+    changed: list[Path] = []
+    for path, text in planned(root=root).items():
+        if _read(path=path) != text:
+            path.write_text(text, encoding="utf-8")
+            changed.append(path)
+    return changed
+
+
+def _read(*, path: Path) -> str | None:
+    if not path.is_file():
+        return None
+    return path.read_text(encoding="utf-8")