Skip to content

Inspect detail

inspect_detail

Detail-building helpers for InspectTool.

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
Python
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
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

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
Python
150
151
152
153
154
155
156
157
158
159
160
161
162
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),
    }

class_detail(sym, *, file='')

Build detail dict from a ClassInfo.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py
Python
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
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

function_detail(sym, *, file='')

Build detail dict from a FunctionInfo.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py
Python
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def function_detail(
    sym: FunctionInfo,
    *,
    file: str = "",
) -> dict[str, object]:
    """Build detail dict from a FunctionInfo."""
    detail: dict[str, object] = {
        "name": sym.name,
        "kind": "function",
        "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

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
Python
116
117
118
119
120
121
122
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 ""

relative_path(pkg, mod_path)

Compute relative path from package root.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py
Python
40
41
42
43
44
45
def relative_path(pkg: PackageInfo, mod_path: Path) -> str:
    """Compute relative path from package root."""
    try:
        return str(mod_path.relative_to(pkg.root.parent))
    except (ValueError, AttributeError):
        return str(mod_path)

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
Python
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
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)

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
Python
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
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_function_text(detail)

Render a function detail dict as compact text.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py
Python
 95
 96
 97
 98
 99
100
101
102
103
104
105
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_module_text(detail)

Render a module detail dict as compact text.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py
Python
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
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(detail)

Dispatch to the correct renderer based on detail kind.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py
Python
174
175
176
177
178
179
180
181
182
183
184
185
186
187
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 "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_variable_text(detail)

Render a variable detail dict as compact text.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_text.py
Python
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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)

variable_detail(sym, *, file='')

Build detail dict from a VariableInfo.

Source code in packages/axm-ast/src/axm_ast/tools/inspect_detail.py
Python
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
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