Inspect Detail Helpers

Internal builders and renderers for ast_inspect; these are not root exports. Module metadata contains name, kind, file, docstring, functions, classes, and symbol_count, not imports or line ranges.

Signatures and docstrings below are rendered from the checkout during the build.

build_detail

build_detail(sym, *, file='', abs_path='', source=False)

Build detail dict from a FunctionInfo, ClassInfo, or VariableInfo.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py

def build_detail(
    sym: FunctionInfo | ClassInfo | VariableInfo,
    *,
    file: str = "",
    abs_path: str = "",
    source: bool = False,
) -> dict[str, object]:
    """Build detail dict from a FunctionInfo, ClassInfo, or VariableInfo."""
    if isinstance(sym, VariableInfo):
        detail = variable_detail(sym, file=file)
        if source and abs_path:
            detail["source"] = read_source(abs_path, sym.line, sym.line)
        return detail

    if isinstance(sym, FunctionInfo):
        detail = function_detail(sym, file=file)
    else:
        detail = class_detail(sym, file=file)

    if source and abs_path:
        detail["source"] = read_source(abs_path, sym.line_start, sym.line_end)

    return detail

read_source

read_source(abs_file_path, start, end)

Read source lines from a file (absolute path).

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py

def read_source(abs_file_path: str, start: int, end: int) -> str:
    """Read source lines from a file (absolute path)."""
    try:
        lines = Path(abs_file_path).read_text().splitlines()
        return "\n".join(lines[start - 1 : end])
    except (OSError, IndexError):
        return ""

variable_detail

variable_detail(sym, *, file='')

Build detail dict from a VariableInfo.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py

def variable_detail(
    sym: VariableInfo,
    *,
    file: str = "",
) -> dict[str, object]:
    """Build detail dict from a VariableInfo."""
    detail: dict[str, object] = {
        "name": sym.name,
        "file": file,
        "kind": "variable",
        "start_line": sym.line,
        "end_line": sym.line,
    }
    if sym.annotation is not None:
        detail["annotation"] = sym.annotation
    if sym.value_repr is not None:
        detail["value_repr"] = sym.value_repr
    return detail

function_detail

function_detail(sym, *, file='')

Build detail dict from a FunctionInfo.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py

def function_detail(
    sym: FunctionInfo,
    *,
    file: str = "",
) -> dict[str, object]:
    """Build detail dict from a FunctionInfo."""
    detail: dict[str, object] = {
        "name": sym.name,
        "kind": sym.kind.value,
        "file": file,
        "start_line": sym.line_start,
        "end_line": sym.line_end,
    }
    if sym.docstring is not None:
        detail["docstring"] = sym.docstring
    detail["signature"] = sym.signature
    if sym.return_type is not None:
        detail["return_type"] = sym.return_type
    if sym.params:
        detail["parameters"] = [
            {"name": p.name, "annotation": p.annotation, "default": p.default}
            for p in sym.params
        ]
    return detail

class_detail

class_detail(sym, *, file='')

Build detail dict from a ClassInfo.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py

def class_detail(
    sym: ClassInfo,
    *,
    file: str = "",
) -> dict[str, object]:
    """Build detail dict from a ClassInfo."""
    detail: dict[str, object] = {
        "name": sym.name,
        "kind": "class",
        "file": file,
        "start_line": sym.line_start,
        "end_line": sym.line_end,
    }
    if sym.docstring is not None:
        detail["docstring"] = sym.docstring
    if sym.bases:
        detail["bases"] = sym.bases
    if sym.methods:
        detail["methods"] = [m.name for m in sym.methods]
    return detail

build_module_detail

build_module_detail(pkg, mod, name)

Build detail dict for a module.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py

def build_module_detail(
    pkg: PackageInfo, mod: ModuleInfo, name: str
) -> dict[str, object]:
    """Build detail dict for a module."""
    return {
        "name": name,
        "kind": "module",
        "file": relative_path(pkg, mod.path),
        "docstring": mod.docstring or "",
        "functions": [f.name for f in mod.functions],
        "classes": [c.name for c in mod.classes],
        "symbol_count": len(mod.functions) + len(mod.classes),
    }

render_function_text

render_function_text(detail)

Render a function detail dict as compact text.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py

def render_function_text(detail: Mapping[str, object]) -> str:
    """Render a function detail dict as compact text."""
    name = _as_str(detail["name"])
    file = _as_str(detail["file"])
    start = _as_int(detail.get("start_line"))
    end = _as_int(detail.get("end_line"), start)

    lines = [_header(name, file, start, end)]
    _append_function_body(lines, detail)
    _append_source(lines, detail)
    return "\n".join(lines)

render_class_text

render_class_text(detail)

Render a class detail dict as compact text.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py

def render_class_text(detail: Mapping[str, object]) -> str:
    """Render a class detail dict as compact text."""
    name = _as_str(detail["name"])
    file = _as_str(detail["file"])
    start = _as_int(detail.get("start_line"))
    end = _as_int(detail.get("end_line"), start)
    bases = _as_str_list(detail.get("bases"))

    suffix = f"({', '.join(bases)})" if bases else ""
    lines = [_header(name, file, start, end, suffix)]

    doc = detail.get("docstring")
    if isinstance(doc, str) and doc:
        lines.append(_truncate_docstring(doc))

    methods = _as_str_list(detail.get("methods"))
    if methods:
        lines.append(f"Methods: {', '.join(methods)}")

    _append_source(lines, detail)
    return "\n".join(lines)

render_variable_text

render_variable_text(detail)

Render a variable detail dict as compact text.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py

def render_variable_text(detail: Mapping[str, object]) -> str:
    """Render a variable detail dict as compact text."""
    name = _as_str(detail["name"])
    file = _as_str(detail["file"])
    start = _as_int(detail.get("start_line"))
    end = _as_int(detail.get("end_line"), start)

    lines = [_header(name, file, start, end, "variable")]

    ann = detail.get("annotation")
    if isinstance(ann, str) and ann:
        lines.append(f": {ann}")

    val = detail.get("value_repr")
    if isinstance(val, str) and val:
        lines.append(f"= {val}")

    return "\n".join(lines)

render_module_text

render_module_text(detail)

Render a module detail dict as compact text.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py

def render_module_text(detail: Mapping[str, object]) -> str:
    """Render a module detail dict as compact text."""
    name = _as_str(detail["name"])
    file = _as_str(detail.get("file"))
    count = _as_int(detail.get("symbol_count"))

    lines = [f"{name}  {file}  module · {count} symbols"]

    doc = detail.get("docstring")
    if isinstance(doc, str) and doc:
        lines.append(_truncate_docstring(doc))

    funcs = _as_str_list(detail.get("functions"))
    if funcs:
        lines.append(f"Functions: {', '.join(funcs)}")

    classes = _as_str_list(detail.get("classes"))
    if classes:
        lines.append(f"Classes: {', '.join(classes)}")

    return "\n".join(lines)

render_symbol_text

render_symbol_text(detail)

Dispatch to the correct renderer based on detail kind.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py

def render_symbol_text(detail: Mapping[str, object]) -> str:
    """Dispatch to the correct renderer based on detail kind."""
    kind = _as_str(detail.get("kind"))
    match kind:
        case "function" | "method":
            return render_function_text(detail)
        case "property" | "classmethod" | "staticmethod" | "abstract":
            rendered = render_function_text(detail)
            header, separator, body = rendered.partition("\n")
            return f"{header} @{kind}{separator}{body}"
        case "class":
            return render_class_text(detail)
        case "variable":
            return render_variable_text(detail)
        case "module":
            return render_module_text(detail)
        case _:
            return render_function_text(detail)

render_batch_text

render_batch_text(symbols)

Join individual renders with blank-line separator, handle errors.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py

def render_batch_text(symbols: Sequence[Mapping[str, object]]) -> str:
    """Join individual renders with blank-line separator, handle errors."""
    if not symbols:
        return ""

    parts: list[str] = []
    for entry in symbols:
        if "error" in entry:
            name = _as_str(entry.get("name"), "?")
            error = _as_str(entry.get("error"))
            parts.append(f"{name}  ⚠ {error}")
        else:
            parts.append(render_symbol_text(entry))

    return "\n\n".join(parts)