Generated API

The narrative API reference specifies imports, limits and failure behavior. These source-derived signatures are a companion, not a replacement. In particular, renderer docstrings use “lossless” for field-oriented display; see rendering limits before treating text as data.

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.

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.

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".

console_script(name, *, executable=None)

Return the path of console script name for the running environment.

Looks next to the interpreter first (where an installed entry point lands), then falls back to PATH, then to the bare name so an unusual layout — or a caller that genuinely wants PATH resolution at exec time — still works.

Parameters:

Name	Type	Description	Default
name	str	The console-script name, e.g. "axm".	required
executable	str | None	Interpreter whose environment to search; defaults to :data:sys.executable (injectable for tests).	None

Returns:

Type	Description
str	An absolute path when the script was found, else name unchanged.

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.

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.

format_count(n)

Format counts in 1000 steps through no suffix, K, M, then B.

Counts below 1000 have no decimal; all abbreviated bands have one. Negative input follows the same scaling, so -1500 renders as '-1.5K'.

format_duration(millis)

Render a millisecond duration as a short human string.

Rendering bands are milliseconds for 0 <= millis < 1000, seconds for 1000 <= millis < 60000, minutes for 60000 <= millis < 3600000, and hours for millis >= 3600000.

450 → '450ms', 1500 → '1.5s', 90000 → '1.5min', 5400000 → '1.5h'. Bands round to at most one decimal (rounded, not truncated). Negative, non-numeric or non-finite input returns 'n/a' without raising.

format_size(num_bytes)

Format bytes in 1024 steps through B, KB, MB, GB, TB, then PB.

B has no decimal; all other bands have one. Negative input follows the same scaling, so -2048 renders as '-2.0 KB'.

header(tool, summary)

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

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

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".

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.

tally_outcomes(lines)

Count pytest outcome lines per kind.

Parameters:

Name	Type	Description	Default
lines	Iterable[object]	An iterable of outcome lines (typically pytest short-summary lines such as "FAILED tests/..."). Non-string / None / malformed elements are tolerated.	required

Returns:

Type	Description
dict[str, int]	A dict with the fixed keys failed/error/skipped/unknown
dict[str, int]	(each always present, initialised to 0). Every input element
dict[str, int]	increments exactly one bucket, so the bucket sum equals the number of
dict[str, int]	elements.

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.

parse_workspace_members(text)

Extract the raw [tool.uv.workspace].members from pyproject text.

Pure-string helper: parses text with :func:tomllib.loads and returns the declared string members verbatim -- no glob expansion, no filesystem access, no exclude/require_pyproject filtering. Globs (packages/*) and literal string entries are returned exactly as written; non-string entries (malformed TOML with e.g. integer members) are skipped, matching :func:resolve_workspace. Defensive: malformed TOML or an absent [tool.uv.workspace] table yields [] rather than raising.

Parameters:

Name	Type	Description	Default
text	str	Raw pyproject.toml content.	required

Returns:

Type	Description
list[str]	The raw member strings declared under [tool.uv.workspace].members,
list[str]	or [] when none are declared.

render_result(tool, data, *, label='')

Render an arbitrary tool result as compact, lossless text.

Header is {tool} (plus | {label} when label is given); the body preserves every field of data. A scalar-only payload collapses to the arrow form {header} → {value}.

Never raises: any object — including an unrenderable or self-referential one — yields a str (falling back to the header line on failure).

record_table(rows, keys, *, indent=0)

Render a homogeneous dict list as key | key header + value rows.

Lossless: emits the shared keys once as a header line then one value row per record. None cells render as an em-dash, bools as yes/no. indent offsets every line by two spaces per level.