Skip to content

AXM Logo

axm-ingot

Shared helper library for the AXM forge.

CI axm-audit axm-init Coverage PyPI Python 3.12+

What it does

axm-ingot is the AXM forge's shared helper library — the single home for small, general-purpose functions that more than one package needs. Logic that would otherwise be copy-pasted (and re-tested) across axm-ast, axm-audit, axm-init and axm-anvil lives here once, is tested once, and is imported as a normal workspace dependency. It is a pure library: no CLI, no MCP tool, no side effects.

Helper Kind What it returns
resolve_workspace(dir) function A ResolvedWorkspace (sorted, exclude-aware) or None
find_project_root(start) function Nearest ancestor with any pyproject.toml (never None)
find_workspace_root(start) function Nearest uv-workspace root, or None
parse_workspace_members(text) function Raw members strings from pyproject text
ResolvedWorkspace / Member dataclass Frozen value objects describing the result

Quick Example

Python
from pathlib import Path

from axm_ingot import resolve_workspace, find_workspace_root

# Resolve a uv workspace to its members (sorted, exclude-aware, require_pyproject)
workspace = resolve_workspace(Path("/path/to/workspace"))
if workspace is not None:
    for member in workspace.members:
        print(member.name, "->", member.path)

# Walk up from any directory to the enclosing uv-workspace root
root = find_workspace_root(Path.cwd())

Features

  • uv-workspace resolution — resolve_workspace parses [tool.uv.workspace], expands members globs, subtracts exclude, enforces require_pyproject, and returns members sorted by name
  • Project-root discovery — find_project_root walks parents to the first pyproject.toml of any kind, always returning a Path (never None); find_workspace_root stops at the first [tool.uv.workspace] specifically
  • Raw members parsing — parse_workspace_members reads the declared member strings from pyproject text verbatim (no globs, no filesystem)
  • Frozen value types — ResolvedWorkspace and Member are stdlib @dataclass(frozen=True) records
  • Zero dependencies — stdlib only (tomllib, pathlib, dataclasses); a true leaf of the forge dependency graph
  • Defensive — an absent or malformed pyproject.toml returns None/[], never raises

Learn More