Index

axm_ingot

axm-ingot.

Canonical shared helpers factored out of duplicated AXM code.

Member dataclass

A single uv-workspace member.

Attributes:

Name	Type	Description
name	str	Basename of the member directory -- not the [project].name declared in the member's pyproject.toml. Two globs resolving to same-named directories (e.g. packages/core and libs/core) therefore yield two members with equal name; callers indexing by name must account for the collision. Read the package name from the member's pyproject.toml (path locates it) when needed.
path	Path	Absolute, resolved path to the member directory.

Source code in packages/axm-ingot/src/axm_ingot/uv/models.py

@dataclass(frozen=True)
class Member:
    """A single uv-workspace member.

    Attributes:
        name: Basename of the member *directory* -- not the ``[project].name``
            declared in the member's ``pyproject.toml``. Two globs resolving to
            same-named directories (e.g. ``packages/core`` and ``libs/core``)
            therefore yield two members with equal ``name``; callers indexing by
            ``name`` must account for the collision. Read the package name from
            the member's ``pyproject.toml`` (``path`` locates it) when needed.
        path: Absolute, resolved path to the member directory.
    """

    name: str
    path: Path

ResolvedWorkspace dataclass

A uv workspace with its resolved members.

Attributes:

Name	Type	Description
root	Path	Absolute path to the workspace root (holding the root pyproject).
members	tuple[Member, ...]	Members sorted by name.

Source code in packages/axm-ingot/src/axm_ingot/uv/models.py

@dataclass(frozen=True)
class ResolvedWorkspace:
    """A uv workspace with its resolved members.

    Attributes:
        root: Absolute path to the workspace root (holding the root pyproject).
        members: Members sorted by name.
    """

    root: Path
    members: tuple[Member, ...]

compact_table(rows, headers=None)

Render rows as a column-aligned table, optionally with a headers row.

Tolerates ragged rows (short rows are padded) and arbitrarily wide cells. None cells render as empty, never as the literal "None".

Source code in packages/axm-ingot/src/axm_ingot/render.py

def compact_table(
    rows: Sequence[Sequence[object]],
    headers: Sequence[object] | None = None,
) -> str:
    """Render *rows* as a column-aligned table, optionally with a *headers* row.

    Tolerates ragged rows (short rows are padded) and arbitrarily wide cells.
    ``None`` cells render as empty, never as the literal ``"None"``.
    """
    matrix: list[list[str]] = []
    if headers is not None:
        matrix.append([_cell(h) for h in headers])
    matrix.extend([_cell(c) for c in row] for row in rows)
    if not matrix:
        return ""
    ncols = max(len(row) for row in matrix)
    for row in matrix:
        row.extend([""] * (ncols - len(row)))
    widths = [max(len(row[col]) for row in matrix) for col in range(ncols)]
    out = []
    for row in matrix:
        line = _COL_SEP.join(row[col].ljust(widths[col]) for col in range(ncols))
        out.append(line.rstrip())
    return "\n".join(out)

find_project_root(start)

Walk parents from start to the first directory holding any pyproject.

Returns the directory of the first ancestor (start included) that contains a pyproject.toml -- any project, not necessarily a uv workspace. start is resolved first; a file start is anchored on its parent directory. Unlike :func:find_workspace_root, this never returns None: with no pyproject.toml in any ancestor it falls back to the (resolved) starting directory.

Source code in packages/axm-ingot/src/axm_ingot/uv/resolve.py

def find_project_root(start: Path) -> Path:
    """Walk parents from ``start`` to the first directory holding any pyproject.

    Returns the directory of the first ancestor (``start`` included) that
    contains a ``pyproject.toml`` -- any project, not necessarily a uv
    workspace. ``start`` is resolved first; a file ``start`` is anchored on its
    parent directory. Unlike :func:`find_workspace_root`, this never returns
    ``None``: with no ``pyproject.toml`` in any ancestor it falls back to the
    (resolved) starting directory.
    """
    current = start.resolve()
    if current.is_file():
        current = current.parent
    for candidate in (current, *current.parents):
        if (candidate / _PYPROJECT).is_file():
            return candidate
    return current

find_workspace_root(path)

Walk parents from path to the first uv-workspace root.

Returns the directory of the first ancestor (path included) whose pyproject.toml carries a [tool.uv.workspace] section, else None.

Source code in packages/axm-ingot/src/axm_ingot/uv/resolve.py

def find_workspace_root(path: Path) -> Path | None:
    """Walk parents from ``path`` to the first uv-workspace root.

    Returns the directory of the first ancestor (``path`` included) whose
    ``pyproject.toml`` carries a ``[tool.uv.workspace]`` section, else ``None``.
    """
    current = path.resolve()
    for directory in (current, *current.parents):
        data = _load_pyproject(directory)
        if data is not None and _get_workspace_config(data) is not None:
            return directory
    return None

format_count(n)

Render an item count, abbreviating thousands (1500 → '1.5K').

Source code in packages/axm-ingot/src/axm_ingot/render.py

def format_count(n: int) -> str:
    """Render an item count, abbreviating thousands (``1500`` → ``'1.5K'``)."""
    magnitude = abs(n)
    if magnitude < _COUNT_STEP:
        return str(n)
    for unit, divisor in (("B", 1_000_000_000), ("M", 1_000_000), ("K", 1_000)):
        if magnitude >= divisor:
            return f"{n / divisor:.1f}{unit}"
    return str(n)

format_size(num_bytes)

Render a byte count in human units (2048 → '2.0 KB').

Source code in packages/axm-ingot/src/axm_ingot/render.py

def format_size(num_bytes: int) -> str:
    """Render a byte count in human units (``2048`` → ``'2.0 KB'``)."""
    size = float(num_bytes)
    units = ("B", "KB", "MB", "GB", "TB", "PB")
    for unit in units:
        if abs(size) < _SIZE_STEP or unit == units[-1]:
            if unit == "B":
                return f"{int(size)} {unit}"
            return f"{size:.1f} {unit}"
        size /= _SIZE_STEP
    return f"{num_bytes} B"

header(tool, summary)

Render the compact header line {tool} | {summary}.

header("audit", "3 findings") 'audit | 3 findings'

Source code in packages/axm-ingot/src/axm_ingot/render.py

def header(tool: str, summary: str) -> str:
    """Render the compact header line ``{tool} | {summary}``.

    >>> header("audit", "3 findings")
    'audit | 3 findings'
    """
    return f"{tool} | {summary}"

labeled_block(label, lines)

Render label followed by lines, each indented two spaces.

An empty lines yields an empty string so no dangling label is emitted. None entries render as blank lines rather than the literal "None".

Source code in packages/axm-ingot/src/axm_ingot/render.py

def labeled_block(label: str, lines: Sequence[str | None]) -> str:
    """Render *label* followed by *lines*, each indented two spaces.

    An empty *lines* yields an empty string so no dangling label is emitted.
    ``None`` entries render as blank lines rather than the literal ``"None"``.
    """
    if not lines:
        return ""
    body = [f"{_INDENT}{_cell(line)}" for line in lines]
    return "\n".join([label, *body])

resolve_workspace(pyproject_dir)

Resolve the uv workspace rooted at pyproject_dir.

Parses [tool.uv.workspace].members, resolves the globs to directories, subtracts the exclude globs, keeps only directories that contain a pyproject.toml (require_pyproject), and returns the members sorted by name. Returns None when pyproject_dir is not a uv workspace or its pyproject is missing/malformed.

Source code in packages/axm-ingot/src/axm_ingot/uv/resolve.py

def resolve_workspace(pyproject_dir: Path) -> ResolvedWorkspace | None:
    """Resolve the uv workspace rooted at ``pyproject_dir``.

    Parses ``[tool.uv.workspace].members``, resolves the globs to directories,
    subtracts the ``exclude`` globs, keeps only directories that contain a
    ``pyproject.toml`` (``require_pyproject``), and returns the members sorted
    by name. Returns ``None`` when ``pyproject_dir`` is not a uv workspace or
    its pyproject is missing/malformed.
    """
    root = pyproject_dir.resolve()
    data = _load_pyproject(root)
    if data is None:
        return None
    workspace = _get_workspace_config(data)
    if workspace is None:
        return None

    included = _resolve_glob_dirs(root, workspace.get("members"))
    excluded = _resolve_glob_dirs(root, workspace.get("exclude"))
    members = tuple(
        sorted(
            (
                Member(name=directory.name, path=directory)
                for directory in included - excluded
                if (directory / _PYPROJECT).is_file()
            ),
            key=lambda member: member.name,
        )
    )
    return ResolvedWorkspace(root=root, members=members)

truncate(text, limit)

Bound text to limit chars, appending an ellipsis when it overflows.

Text at or under limit is returned unchanged. The overflow result has at most limit + 1 characters and ends with the ellipsis marker.

Source code in packages/axm-ingot/src/axm_ingot/render.py

def truncate(text: str, limit: int) -> str:
    """Bound *text* to *limit* chars, appending an ellipsis when it overflows.

    Text at or under *limit* is returned unchanged. The overflow result has at
    most ``limit + 1`` characters and ends with the ellipsis marker.
    """
    bound = max(limit, 0)
    if len(text) <= bound:
        return text
    return text[:bound] + _ELLIPSIS