python-checks 0.1.0__py3-none-any.whl

py_checks/config/_toml.py

@@ -0,0 +1,24 @@
+"""Типы значений, какими их отдаёт `tomllib`."""
+
+from __future__ import annotations
+
+import datetime
+
+type TomlValue = (
+    bool
+    | int
+    | float
+    | str
+    | datetime.datetime
+    | datetime.date
+    | datetime.time
+    | list[TomlValue]
+    | TomlTable
+)
+
+type TomlTable = dict[str, TomlValue]
+"""Таблица TOML: секция конфига до того, как её разобрала модель.
+
+Не `dict[str, Any]`: `Any` отключает проверку типов у всех, кто такую таблицу
+получит, а здесь заранее известно, что значения бывают ровно этих видов.
+"""

py_checks/contracts/__init__.py

@@ -0,0 +1,26 @@
+"""Контракты импортов для import-linter.
+
+Как называются слои и кому что можно — знает проект, а не библиотека: в
+сервисе это `domain` и `presentation`, в утилите — `core` и `cli`, и придумать
+за них нельзя. Проект описывает это в `[tool.py-checks.contracts]`, а
+`py-checks sync` собирает контракты под его раскладку: слои, которых на
+диске нет, в файл не попадают, иначе import-linter упал бы на первом же
+несуществующем модуле.
+
+Собранный файл править нечего — перезапишет следующий sync; менять нужно
+секцию.
+"""
+
+from py_checks.contracts._constants import FILE, MIGRATIONS, MODULES, SECTION
+from py_checks.contracts._render import render
+from py_checks.contracts._settings import Contracts, contracts
+
+__all__ = [
+    "FILE",
+    "MIGRATIONS",
+    "MODULES",
+    "SECTION",
+    "Contracts",
+    "contracts",
+    "render",
+]

py_checks/contracts/_constants.py

@@ -0,0 +1,18 @@
+"""Имена, из которых собираются контракты импортов."""
+
+from __future__ import annotations
+
+from typing import Final
+
+FILE: Final = ".importlinter"
+
+# Пакет с модулями приложения: слои живут и в нём, и рядом с ним.
+MODULES: Final = "modules"
+
+MIGRATIONS: Final = "migrations"
+
+# Проверяется только история: `env.py` рядом — не миграция, а запускающий её
+# код, и метаданные моделей он импортирует по своей работе.
+VERSIONS: Final = "versions"
+
+SECTION: Final = "contracts"

py_checks/contracts/_layout.py

@@ -0,0 +1,63 @@
+"""Где в проекте лежат слои.
+
+Контракт с несуществующим модулем валит весь прогон import-linter, поэтому
+генератор сначала смотрит, что на диске есть. Подстановка (`pkg.modules.*.domain`)
+ничего не ломает, когда не находит ничего, — её можно писать всегда.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from py_checks.contracts._constants import MIGRATIONS, MODULES, VERSIONS
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def package(
+    *,
+    root: Path,
+    src: Path,
+) -> str | None:
+    """Корневой пакет проекта: единственный пакет внутри `src`."""
+    source = root / src
+    if not source.is_dir():
+        return None
+    found = [
+        directory.name
+        for directory in sorted(source.iterdir())
+        if directory.is_dir() and (directory / "__init__.py").is_file()
+    ]
+    if len(found) != 1:
+        return None
+    return found[0]
+
+
+def expressions(
+    *,
+    root: Path,
+    src: Path,
+    package: str,
+    layer: str,
+) -> tuple[str, ...]:
+    """Как назвать слой в контракте: сам по себе, внутри модулей, или никак."""
+    found: list[str] = []
+    if (root / src / package / layer).is_dir():
+        found.append(f"{package}.{layer}")
+    if (root / src / package / MODULES).is_dir():
+        found.append(f"{package}.{MODULES}.*.{layer}")
+    return tuple(found)
+
+
+def modules(
+    *,
+    root: Path,
+    src: Path,
+    package: str,
+) -> bool:
+    return (root / src / package / MODULES).is_dir()
+
+
+def migrations(*, root: Path) -> bool:
+    return (root / MIGRATIONS / VERSIONS).is_dir()

py_checks/contracts/_render.py

@@ -0,0 +1,217 @@
+"""Сборка файла контрактов для import-linter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+from py_checks.config import prefix
+from py_checks.contracts._constants import MIGRATIONS, MODULES, SECTION, VERSIONS
+from py_checks.contracts._layout import expressions, migrations, modules, package
+from py_checks.contracts._settings import contracts
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping, Sequence
+    from pathlib import Path
+
+    from py_checks.config import Config
+
+HEADER: Final = """\
+# Контракты импортов. Файл собирает `py-checks sync` из того, какие слои
+# есть на диске, и из секции [{section}] — править его нечего, следующий sync
+# перезапишет. Менять нужно секцию.
+"""
+
+
+def render(
+    *,
+    root: Path,
+    config: Config,
+) -> str | None:
+    """Файл контрактов; `None`, если проверять нечего.
+
+    Нечего — это либо проект, который не объявил ни одного слоя, либо
+    раскладка, в которой объявленных слоёв нет на диске.
+    """
+    name = package(
+        root=root,
+        src=config.src,
+    )
+    if name is None:
+        return None
+    blocks = _contracts(
+        root=root,
+        config=config,
+        package=name,
+    )
+    if not blocks:
+        return None
+    return "\n".join(
+        [
+            # Секция зовётся по-разному в манифесте и в своём файле настроек:
+            # написать одно имя значит послать читателя не туда в половине
+            # проектов.
+            HEADER.format(section=f"{prefix(source=config.origin)}{SECTION}"),
+            _roots(
+                root=root,
+                package=name,
+            ),
+            *blocks,
+        ]
+    )
+
+
+def _roots(
+    *,
+    root: Path,
+    package: str,
+) -> str:
+    packages = [package, MIGRATIONS] if migrations(root=root) else [package]
+    return _block(
+        head="[importlinter]",
+        scalars={},
+        lists={"root_packages": packages},
+    )
+
+
+def _contracts(
+    *,
+    root: Path,
+    config: Config,
+    package: str,
+) -> list[str]:
+    declared = contracts(config=config)
+    table = declared.layers
+    known = frozenset(table) | frozenset(declared.composition_root)
+    blocks = [
+        block
+        for layer in sorted(table)
+        if (
+            block := _layer(
+                root=root,
+                config=config,
+                package=package,
+                layer=layer,
+                forbidden=known - frozenset(table[layer]),
+            )
+        )
+    ]
+    blocks.extend(
+        _independence(
+            root=root,
+            config=config,
+            package=package,
+        )
+    )
+    blocks.extend(
+        _migrations(
+            root=root,
+            package=package,
+        )
+    )
+    return blocks
+
+
+def _layer(
+    *,
+    root: Path,
+    config: Config,
+    package: str,
+    layer: str,
+    forbidden: Iterable[str],
+) -> str | None:
+    """Контракт «этому слою нельзя вот это»."""
+    sources = expressions(
+        root=root,
+        src=config.src,
+        package=package,
+        layer=layer,
+    )
+    targets = [
+        expression
+        for other in sorted(forbidden)
+        for expression in expressions(
+            root=root,
+            src=config.src,
+            package=package,
+            layer=other,
+        )
+    ]
+    if not sources or not targets:
+        return None
+    return _block(
+        head=f"[importlinter:contract:layer-{layer}]",
+        scalars={
+            "name": f"{layer} не импортирует чужое",
+            "type": "forbidden",
+            # Только прямые импорты. Непрямую цепочку тут проверять нечего:
+            # `presentation` зовёт `application`, а `application` знает
+            # `domain` — по таблице это и есть правильная работа, и запрет
+            # непрямых связей запретил бы её же.
+            "allow_indirect_imports": "True",
+        },
+        lists={"source_modules": list(sources), "forbidden_modules": targets},
+    )
+
+
+def _independence(
+    *,
+    root: Path,
+    config: Config,
+    package: str,
+) -> list[str]:
+    """Модули друг о друге не знают: соседа зовут через порт, а не по имени."""
+    if not modules(
+        root=root,
+        src=config.src,
+        package=package,
+    ):
+        return []
+    return [
+        _block(
+            head="[importlinter:contract:modules]",
+            scalars={"name": "модули независимы", "type": "independence"},
+            lists={"modules": [f"{package}.{MODULES}.*"]},
+        ),
+    ]
+
+
+def _migrations(
+    *,
+    root: Path,
+    package: str,
+) -> list[str]:
+    """Миграция описывает схему, а не зовёт приложение: код уедет, схема останется.
+
+    Смотрим только на `versions`: `env.py` — не история, а то, что её запускает,
+    и метаданные моделей он импортирует по своей работе.
+    """
+    if not migrations(root=root):
+        return []
+    return [
+        _block(
+            head=f"[importlinter:contract:{MIGRATIONS}]",
+            scalars={"name": "миграции не знают приложение", "type": "forbidden"},
+            lists={
+                "source_modules": [f"{MIGRATIONS}.{VERSIONS}"],
+                "forbidden_modules": [package],
+            },
+        ),
+    ]
+
+
+def _block(
+    *,
+    head: str,
+    scalars: Mapping[str, str],
+    lists: Mapping[str, Sequence[str]],
+) -> str:
+    """Один раздел ini.
+
+    Списки пишутся в столбик даже из одного значения: import-linter разбирает
+    поле-список, написанное в строку, посимвольно — и ищет пакет `p`.
+    """
+    lines = [head, *(f"{key} = {value}" for key, value in scalars.items())]
+    for key, values in lists.items():
+        lines.append(f"{key} =")
+        lines.extend(f"    {value}" for value in values)
+    return "\n".join(lines) + "\n"

py_checks/contracts/_settings.py

@@ -0,0 +1,37 @@
+"""Слои проекта: что он объявил о себе сам."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import ValidationError
+
+from py_checks.config import CheckSettings, ConfigError
+from py_checks.contracts._constants import SECTION
+
+if TYPE_CHECKING:
+    from py_checks.config import Config
+
+
+class Contracts(CheckSettings):
+    """Секция `[tool.py-checks.contracts]`.
+
+    `layers` — слой и то, что ему разрешено импортировать. Всё, чего в таблице
+    нет, ограничений не имеет: библиотека не знает, как называются слои в этом
+    проекте, и не догадывается за него.
+
+    `composition-root` — слои, которым можно всё: они связывают остальные между
+    собой, и это вся их работа. Перечислять их отдельно нужно затем, чтобы они
+    попали в запреты остальных: слой, о котором таблица не знает, ничьим
+    запретом не становится.
+    """
+
+    composition_root: tuple[str, ...] = ()
+    layers: dict[str, tuple[str, ...]] = {}
+
+
+def contracts(*, config: Config) -> Contracts:
+    try:
+        return Contracts.model_validate(config.section(code=SECTION))
+    except ValidationError as error:
+        raise ConfigError(f"[tool.py-checks.{SECTION}]: {error}") from error

py_checks/core/__init__.py

@@ -0,0 +1,56 @@
+"""Общая часть всех проверок.
+
+Поиск файлов, разбор исходника один раз на файл, описание нарушения, реестр
+проверок и вывод. Правило знает только своё условие, всё остальное берёт
+отсюда.
+"""
+
+from py_checks.core._constants import EXIT_OK, EXIT_VIOLATION, GROUP
+from py_checks.core._discovery import python_files
+from py_checks.core._edit import Edit, apply, column
+from py_checks.core._errors import ParseError, UnknownCheckError
+from py_checks.core._fixer import fix
+from py_checks.core._format import reformat
+from py_checks.core._markers import MARKER, Marker, complaints, read, surviving
+from py_checks.core._protocols import Check, FileCheck, ProjectCheck, Scope
+from py_checks.core._registry import Checks, available, get
+from py_checks.core._report import report
+from py_checks.core._runner import SYNTAX, examine, inspect, survey
+from py_checks.core._settings import SettingsMismatchError, settings_as
+from py_checks.core._source import ParsedFile
+from py_checks.core._violation import Violation
+
+__all__ = [
+    "EXIT_OK",
+    "EXIT_VIOLATION",
+    "GROUP",
+    "MARKER",
+    "SYNTAX",
+    "Check",
+    "Checks",
+    "Edit",
+    "FileCheck",
+    "ProjectCheck",
+    "Marker",
+    "ParseError",
+    "ParsedFile",
+    "Scope",
+    "SettingsMismatchError",
+    "UnknownCheckError",
+    "Violation",
+    "apply",
+    "available",
+    "column",
+    "complaints",
+    "fix",
+    "examine",
+    "get",
+    "inspect",
+    "python_files",
+    "read",
+    "reformat",
+    "surviving",
+    "settings_as",
+    "report",
+    "survey",
+]

py_checks/core/_constants.py

@@ -0,0 +1,15 @@
+"""Имена и коды, общие для ядра."""
+
+from __future__ import annotations
+
+from typing import Final
+
+# Группа entry points, в которой объявляются проверки: своя проверка живёт в
+# отдельном пакете и не требует форка библиотеки. Группа одна на все виды
+# правил — что правилу дают, файл или корень проекта, оно говорит само.
+GROUP: Final = "py_checks.checks"
+
+# Что видит оболочка. Голая единица была бы кодом, смысл которого знает только
+# вызывающий; pre-commit по ней останавливает коммит.
+EXIT_OK: Final = 0
+EXIT_VIOLATION: Final = 1

py_checks/core/_discovery.py

@@ -0,0 +1,57 @@
+"""Какие файлы проверяем."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatch
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+    from pathlib import Path
+
+
+def python_files(
+    *,
+    paths: Sequence[Path],
+    root: Path,
+    default: Path,
+    exclude: Iterable[str] = (),
+) -> list[Path]:
+    """Все `.py` из переданных путей, без исключённых.
+
+    pre-commit передаёт список изменённых файлов, поэтому путь может быть и
+    файлом, и директорией. Когда путей нет — запуск руками, — берём `default`
+    (обычно `src`), а не весь репозиторий: иначе в выборку попадут `.venv` и
+    прочее чужое.
+    """
+    roots = list(paths) if paths else [default]
+    patterns = tuple(exclude)
+    found: set[Path] = set()
+    for entry in roots:
+        found.update(_walk(entry=entry))
+    return sorted(
+        path
+        for path in found
+        if not _excluded(
+            path=path,
+            root=root,
+            patterns=patterns,
+        )
+    )
+
+
+def _walk(*, entry: Path) -> Iterable[Path]:
+    if entry.is_dir():
+        return entry.rglob("*.py")
+    return [entry] if entry.suffix == ".py" else []
+
+
+def _excluded(
+    *,
+    path: Path,
+    root: Path,
+    patterns: tuple[str, ...],
+) -> bool:
+    relative = path.relative_to(root) if path.is_relative_to(root) else path
+    as_posix = relative.as_posix()
+    return any(fnmatch(as_posix, pattern) for pattern in patterns)

py_checks/core/_edit.py

@@ -0,0 +1,92 @@
+"""Правка исходника и то, как она накладывается."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import accumulate
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+@dataclass(frozen=True, slots=True)
+class Edit:
+    """Замена куска исходника, строки и колонки — как у нарушения, с единицы.
+
+    Вставка — это замена пустого места: начало и конец совпадают. Правка
+    описывает только тот кусок, который меняет, поэтому всё остальное в файле —
+    комментарии, переносы, чужое форматирование — остаётся нетронутым.
+    """
+
+    line: int
+    column: int
+    end_line: int
+    end_column: int
+    text: str
+
+
+def column(
+    *,
+    line: str,
+    offset: int,
+) -> int:
+    """Колонка правки по смещению из дерева, с единицы.
+
+    `ast` считает `col_offset` в БАЙТАХ utf-8, а правка индексирует строку
+    символами. Совпадает это ровно до первого не-ascii символа в строке: одно
+    русское слово в литерале раньше по строке — и запятая встаёт не туда.
+    """
+    return len(line.encode("utf-8")[:offset].decode("utf-8", errors="ignore")) + 1
+
+
+def apply(
+    *,
+    text: str,
+    edits: Sequence[Edit],
+) -> str:
+    """Исходник со всеми правками.
+
+    Накладываются с конца файла к началу: тогда позиции ещё не наложенных
+    правок остаются верными и пересчитывать их не нужно. Правки, залезающие на
+    уже наложенную, пропускаются — две проверки, спорящие за один кусок текста,
+    должны разойтись в разных прогонах, а не перезаписывать друг друга.
+    """
+    starts = _starts(text=text)
+    applied = len(text)
+    result = text
+    for edit in sorted(
+        edits,
+        key=lambda edit: (edit.line, edit.column),
+        reverse=True,
+    ):
+        start = _offset(
+            starts=starts,
+            line=edit.line,
+            column=edit.column,
+        )
+        end = _offset(
+            starts=starts,
+            line=edit.end_line,
+            column=edit.end_column,
+        )
+        if end > applied:
+            continue
+        result = result[:start] + edit.text + result[end:]
+        applied = start
+    return result
+
+
+def _starts(*, text: str) -> tuple[int, ...]:
+    """Смещение начала каждой строки от начала файла."""
+    lengths = (len(line) for line in text.splitlines(keepends=True))
+    return (0, *accumulate(lengths))
+
+
+def _offset(
+    *,
+    starts: Sequence[int],
+    line: int,
+    column: int,
+) -> int:
+    return starts[min(line, len(starts)) - 1] + column - 1

py_checks/core/_errors.py

@@ -0,0 +1,35 @@
+"""Ошибки ядра."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ParseError(Exception):
+    """Файл не разбирается: синтаксис сломан."""
+
+    def __init__(
+        self,
+        *,
+        path: Path,
+        error: SyntaxError,
+    ) -> None:
+        super().__init__(f"{path}: {error.msg}")
+        self.path = path
+        self.error = error
+
+
+class UnknownCheckError(Exception):
+    """Такой проверки нет."""
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        known: tuple[str, ...],
+    ) -> None:
+        super().__init__(f"неизвестная проверка {code!r}; есть: {', '.join(known)}")
+        self.code = code