Skip to content

Describe

describe

DescribeTool — full API surface dump.

DescribeTool

Bases: AXMTool

Describe a package: signatures, docstrings, all.

Registered as ast_describe via axm.tools entry point.

Source code in packages/axm-ast/src/axm_ast/tools/describe.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class DescribeTool(AXMTool):
    """Describe a package: signatures, docstrings, __all__.

    Registered as ``ast_describe`` via axm.tools entry point.
    """

    agent_hint: str = (
        "Show module API: signatures, docstrings, classes, __all__."
        " Use detail=toc for overview, modules=[...] to filter."
        " Replaces 10+ view_file."
    )

    @property
    def name(self) -> str:
        """Return tool name for registry lookup."""
        return "ast_describe"

    def execute(
        self,
        *,
        path: str = ".",
        compress: bool = False,
        detail: str = "summary",
        modules: list[str] | None = None,
        **kwargs: Any,
    ) -> ToolResult:
        """Describe a Python package.

        Args:
            path: Path to package directory.
            compress: If True, return compressed AI-friendly view.
            detail: Detail level — ``toc`` (names + counts only),
                ``summary`` (signatures only),
                ``detailed`` (+ docstrings, params, return types),
                or ``full`` (+ line numbers, imports, variables).
                Defaults to ``summary`` (signatures only, no docstrings).
            modules: Optional list of module name substrings to filter.
                Case-insensitive.  ``None`` or empty returns all modules.

        Returns:
            ToolResult with module descriptions.
        """
        try:
            project_path = Path(path).resolve()
            if not project_path.is_dir():
                return ToolResult(
                    success=False, error=f"Not a directory: {project_path}"
                )

            from axm_ast.core.cache import get_package
            from axm_ast.formatters import (
                filter_modules,
                format_compressed,
                format_json,
                format_toc,
            )

            pkg = get_package(project_path)
            pkg = filter_modules(pkg, modules)

            if detail == "toc":
                toc = format_toc(pkg)
                return ToolResult(
                    success=True,
                    data={
                        "modules": toc,
                        "module_count": len(toc),
                    },
                    hint="Tip: Use ast_impact(symbol) before modifying any symbol.",
                )

            if compress:
                text = format_compressed(pkg)
                return ToolResult(
                    success=True,
                    data={
                        "compressed": text,
                        "module_count": len(pkg.modules),
                    },
                    hint="Tip: Use ast_impact(symbol) before modifying any symbol.",
                )

            data = format_json(pkg, detail=detail)
            return ToolResult(
                success=True,
                data={
                    "modules": data["modules"],
                    "module_count": len(pkg.modules),
                },
                hint="Tip: Use ast_impact(symbol) before modifying any symbol.",
            )
        except Exception as exc:
            return ToolResult(success=False, error=str(exc))
name property

Return tool name for registry lookup.

execute(*, path='.', compress=False, detail='summary', modules=None, **kwargs)

Describe a Python package.

Parameters:

Name Type Description Default
path str

Path to package directory.

 '.'
compress bool

If True, return compressed AI-friendly view.

 False
detail str

Detail level — toc (names + counts only), summary (signatures only), detailed (+ docstrings, params, return types), or full (+ line numbers, imports, variables). Defaults to summary (signatures only, no docstrings).

 'summary'
modules list[str] | None

Optional list of module name substrings to filter. Case-insensitive. None or empty returns all modules.

 None

Returns:

Type Description
ToolResult

ToolResult with module descriptions.
Source code in packages/axm-ast/src/axm_ast/tools/describe.py 
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def execute(
    self,
    *,
    path: str = ".",
    compress: bool = False,
    detail: str = "summary",
    modules: list[str] | None = None,
    **kwargs: Any,
) -> ToolResult:
    """Describe a Python package.

    Args:
        path: Path to package directory.
        compress: If True, return compressed AI-friendly view.
        detail: Detail level — ``toc`` (names + counts only),
            ``summary`` (signatures only),
            ``detailed`` (+ docstrings, params, return types),
            or ``full`` (+ line numbers, imports, variables).
            Defaults to ``summary`` (signatures only, no docstrings).
        modules: Optional list of module name substrings to filter.
            Case-insensitive.  ``None`` or empty returns all modules.

    Returns:
        ToolResult with module descriptions.
    """
    try:
        project_path = Path(path).resolve()
        if not project_path.is_dir():
            return ToolResult(
                success=False, error=f"Not a directory: {project_path}"
            )

        from axm_ast.core.cache import get_package
        from axm_ast.formatters import (
            filter_modules,
            format_compressed,
            format_json,
            format_toc,
        )

        pkg = get_package(project_path)
        pkg = filter_modules(pkg, modules)

        if detail == "toc":
            toc = format_toc(pkg)
            return ToolResult(
                success=True,
                data={
                    "modules": toc,
                    "module_count": len(toc),
                },
                hint="Tip: Use ast_impact(symbol) before modifying any symbol.",
            )

        if compress:
            text = format_compressed(pkg)
            return ToolResult(
                success=True,
                data={
                    "compressed": text,
                    "module_count": len(pkg.modules),
                },
                hint="Tip: Use ast_impact(symbol) before modifying any symbol.",
            )

        data = format_json(pkg, detail=detail)
        return ToolResult(
            success=True,
            data={
                "modules": data["modules"],
                "module_count": len(pkg.modules),
            },
            hint="Tip: Use ast_impact(symbol) before modifying any symbol.",
        )
    except Exception as exc:
        return ToolResult(success=False, error=str(exc))