Skip to content

utils

_utils

Shared utilities for audit check modules.

load_exclusions(project)

Load per-package check exclusions from pyproject.toml.

Reads the [tool.axm-init].exclude key and returns check name prefixes that should be auto-passed for this package.

Example config::

[tool.axm-init]
exclude = ["cli", "changelog", "deps.entry_points"]

Parameters:

Name Type Description Default
project Path

Path to the project root containing pyproject.toml.

 required

Returns:

Type Description
set[str]

Set of check name prefixes to exclude. Empty set if no
set[str]

exclusions are configured.
Source code in packages/axm-init/src/axm_init/checks/_utils.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
def load_exclusions(project: Path) -> set[str]:
    """Load per-package check exclusions from pyproject.toml.

    Reads the ``[tool.axm-init].exclude`` key and returns check name
    prefixes that should be auto-passed for this package.

    Example config::

        [tool.axm-init]
        exclude = ["cli", "changelog", "deps.entry_points"]

    Args:
        project: Path to the project root containing ``pyproject.toml``.

    Returns:
        Set of check name prefixes to exclude.  Empty set if no
        exclusions are configured.
    """
    data = _load_toml(project)
    if data is None:
        return set()

    axm_init_config: dict[str, Any] = data.get("tool", {}).get("axm-init", {})
    if not axm_init_config:
        return set()

    raw = axm_init_config.get("exclude")
    if raw is None:
        return set()

    # Handle string → wrap in list
    if isinstance(raw, str):
        raw = [raw]

    if not isinstance(raw, list):
        logger.warning(
            "Invalid [tool.axm-init].exclude value (expected list): %r",
            raw,
        )
        return set()

    exclusions: set[str] = set()
    for item in raw:
        if isinstance(item, str) and item:
            exclusions.add(item)
        else:
            logger.warning(
                "Invalid exclusion entry in [tool.axm-init].exclude: %r",
                item,
            )

    return exclusions

requires_toml(check_name, category, weight, fix)

Decorator that loads pyproject.toml and passes data to the check.

If pyproject.toml is missing or unparsable, returns a failure CheckResult immediately — eliminating the repeated null-guard preamble from every check function.

The decorated function receives (project, data) instead of just (project) — where data is the parsed TOML dict.

Parameters:

Name Type Description Default
check_name str

Check result name (e.g. "pyproject.ruff").

 required
category str

Category key (e.g. "pyproject").

 required
weight int

Points weight for this check.

 required
fix str

Fix message for the "not found" failure.

 required
Source code in packages/axm-init/src/axm_init/checks/_utils.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def requires_toml(
    check_name: str,
    category: str,
    weight: int,
    fix: str,
) -> Callable[
    [Callable[[Path, dict[str, Any]], CheckResult]],
    Callable[[Path], CheckResult],
]:
    """Decorator that loads pyproject.toml and passes data to the check.

    If pyproject.toml is missing or unparsable, returns a failure
    ``CheckResult`` immediately — eliminating the repeated null-guard
    preamble from every check function.

    The decorated function receives ``(project, data)`` instead of just
    ``(project)`` — where ``data`` is the parsed TOML dict.

    Args:
        check_name: Check result name (e.g. ``"pyproject.ruff"``).
        category: Category key (e.g. ``"pyproject"``).
        weight: Points weight for this check.
        fix: Fix message for the "not found" failure.
    """

    def decorator(
        fn: Callable[[Path, dict[str, Any]], CheckResult],
    ) -> Callable[[Path], CheckResult]:
        """Wrap a check function with TOML pre-loading."""

        @functools.wraps(fn)
        def wrapper(project: Path) -> CheckResult:
            """Load TOML then delegate to the wrapped check."""
            data = _load_toml(project)
            if data is None:
                return CheckResult(
                    name=check_name,
                    category=category,
                    passed=False,
                    weight=weight,
                    message="pyproject.toml not found or unparsable",
                    details=[],
                    fix=fix,
                )
            return fn(project, data)

        return wrapper

    return decorator