api-squash 0.1.0__py3-none-any.whl

api_squash/cli.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from .extractor import extract_file
+from .renderer import render_module, render_project
+from .scanner import scan_directory
+
+
+@click.group()
+def cli() -> None:
+    """Extract Python API surfaces in a compact, token-efficient format."""
+
+
+@cli.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--no-docstrings", is_flag=True, help="Strip all docstrings")
+@click.option(
+    "--no-private", is_flag=True, help="Skip private methods (except __init__)"
+)
+def file(path: str, no_docstrings: bool, no_private: bool) -> None:
+    """Summarize a single Python file."""
+    file_path = Path(path)
+    if file_path.suffix != ".py":
+        click.echo(f"Error: {path} is not a Python file", err=True)
+        sys.exit(1)
+
+    try:
+        module = extract_file(file_path)
+    except SyntaxError as e:
+        click.echo(f"Error: Failed to parse {path}: {e}", err=True)
+        sys.exit(1)
+
+    module.path = Path(path).as_posix()
+
+    output = render_module(module, no_docstrings=no_docstrings, no_private=no_private)
+    click.echo(output, nl=False)
+
+
+@cli.command()
+@click.argument("path", type=click.Path(exists=True, file_okay=False))
+@click.option(
+    "--max-depth", type=int, default=None, help="Limit directory recursion depth"
+)
+@click.option("--exclude", multiple=True, help="Glob patterns to exclude")
+@click.option("--no-docstrings", is_flag=True, help="Strip all docstrings")
+@click.option(
+    "--no-private", is_flag=True, help="Skip private methods (except __init__)"
+)
+def project(
+    path: str,
+    max_depth: int | None,
+    exclude: tuple[str, ...],
+    no_docstrings: bool,
+    no_private: bool,
+) -> None:
+    """Summarize all Python files in a directory."""
+    root = Path(path)
+    files = scan_directory(root, exclude=list(exclude), max_depth=max_depth)
+
+    if not files:
+        click.echo(f"No Python files found in {path}", err=True)
+        return
+
+    modules = []
+    for file_path in files:
+        try:
+            module = extract_file(file_path)
+            module.path = file_path.relative_to(root).as_posix()
+            modules.append(module)
+        except SyntaxError as e:
+            click.echo(f"Warning: Skipping {file_path}: {e}", err=True)
+        except Exception as e:
+            click.echo(f"Warning: Skipping {file_path}: {e}", err=True)
+
+    output = render_project(modules, no_docstrings=no_docstrings, no_private=no_private)
+    click.echo(output, nl=False)

api_squash/extractor.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from .models import ClassSummary, FunctionSummary, ModuleSummary
+
+
+def extract_file(path: Path) -> ModuleSummary:
+    source = path.read_text(encoding="utf-8")
+    tree = ast.parse(source)
+
+    classes: list[ClassSummary] = []
+    functions: list[FunctionSummary] = []
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef):
+            classes.append(_extract_class(node))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.append(_extract_function(node))
+
+    return ModuleSummary(
+        path=path.as_posix(),
+        classes=classes,
+        functions=functions,
+    )
+
+
+def _extract_class(node: ast.ClassDef) -> ClassSummary:
+    docstring = ast.get_docstring(node)
+    bases = [ast.unparse(base) for base in node.bases]
+    methods: list[FunctionSummary] = []
+
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            methods.append(_extract_function(child))
+
+    return ClassSummary(
+        name=node.name,
+        docstring=docstring,
+        methods=methods,
+        bases=bases,
+    )
+
+
+def _extract_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> FunctionSummary:
+    docstring = ast.get_docstring(node)
+    signature = _build_signature(node)
+    is_async = isinstance(node, ast.AsyncFunctionDef)
+
+    return FunctionSummary(
+        name=node.name,
+        signature=signature,
+        docstring=docstring,
+        is_async=is_async,
+    )
+
+
+def _build_signature(node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    args = node.args
+    params: list[str] = []
+
+    # Combine positional-only and regular args for default alignment
+    all_positional = list(args.posonlyargs) + list(args.args)
+    num_positional = len(all_positional)
+    num_defaults = len(args.defaults)
+    default_offset = num_positional - num_defaults
+
+    for i, arg in enumerate(all_positional):
+        part = arg.arg
+        if arg.annotation:
+            part += f": {ast.unparse(arg.annotation)}"
+        default_idx = i - default_offset
+        if default_idx >= 0:
+            part += f" = {ast.unparse(args.defaults[default_idx])}"
+        params.append(part)
+        # Insert "/" separator after positional-only args
+        if args.posonlyargs and i == len(args.posonlyargs) - 1:
+            params.append("/")
+
+    if args.vararg:
+        part = f"*{args.vararg.arg}"
+        if args.vararg.annotation:
+            part += f": {ast.unparse(args.vararg.annotation)}"
+        params.append(part)
+    elif args.kwonlyargs:
+        params.append("*")
+
+    for i, arg in enumerate(args.kwonlyargs):
+        part = arg.arg
+        if arg.annotation:
+            part += f": {ast.unparse(arg.annotation)}"
+        if args.kw_defaults[i] is not None:
+            part += f" = {ast.unparse(args.kw_defaults[i])}"
+        params.append(part)
+
+    if args.kwarg:
+        part = f"**{args.kwarg.arg}"
+        if args.kwarg.annotation:
+            part += f": {ast.unparse(args.kwarg.annotation)}"
+        params.append(part)
+
+    sig = f"({', '.join(params)})"
+    if node.returns:
+        sig += f" -> {ast.unparse(node.returns)}"
+
+    return sig

api_squash/models.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FunctionSummary:
+    name: str
+    signature: str
+    docstring: str | None = None
+    is_async: bool = False
+
+
+@dataclass
+class ClassSummary:
+    name: str
+    docstring: str | None = None
+    methods: list[FunctionSummary] = field(default_factory=list)
+    bases: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ModuleSummary:
+    path: str
+    classes: list[ClassSummary] = field(default_factory=list)
+    functions: list[FunctionSummary] = field(default_factory=list)

api_squash/renderer.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from .models import ClassSummary, FunctionSummary, ModuleSummary
+
+
+def render_module(
+    module: ModuleSummary,
+    *,
+    no_docstrings: bool = False,
+    no_private: bool = False,
+) -> str:
+    lines = [f"# {module.path}"]
+
+    items: list[str] = []
+    for cls in module.classes:
+        items.append(
+            _render_class(cls, no_docstrings=no_docstrings, no_private=no_private)
+        )
+    for func in module.functions:
+        if no_private and _is_private(func.name):
+            continue
+        items.append(_render_function(func, indent=0, no_docstrings=no_docstrings))
+
+    if items:
+        lines.append("")
+        lines.append("\n\n".join(items))
+
+    return "\n".join(lines) + "\n"
+
+
+def render_project(
+    modules: list[ModuleSummary],
+    *,
+    no_docstrings: bool = False,
+    no_private: bool = False,
+) -> str:
+    rendered = [
+        render_module(module, no_docstrings=no_docstrings, no_private=no_private)
+        for module in modules
+    ]
+    return "\n---\n\n".join(rendered)
+
+
+def _render_class(
+    cls: ClassSummary,
+    *,
+    no_docstrings: bool = False,
+    no_private: bool = False,
+) -> str:
+    parts: list[str] = []
+
+    if cls.bases:
+        parts.append(f"class {cls.name}({', '.join(cls.bases)}):")
+    else:
+        parts.append(f"class {cls.name}:")
+
+    if cls.docstring and not no_docstrings:
+        parts.append(_format_docstring(cls.docstring, indent=2))
+
+    for method in cls.methods:
+        if no_private and _is_private(method.name) and method.name != "__init__":
+            continue
+        parts.append(_render_function(method, indent=2, no_docstrings=no_docstrings))
+
+    return "\n".join(parts)
+
+
+def _render_function(
+    func: FunctionSummary,
+    *,
+    indent: int = 0,
+    no_docstrings: bool = False,
+) -> str:
+    prefix = " " * indent
+    parts: list[str] = []
+
+    keyword = "async def" if func.is_async else "def"
+    parts.append(f"{prefix}{keyword} {func.name}{func.signature}")
+
+    if func.docstring and not no_docstrings:
+        parts.append(_format_docstring(func.docstring, indent=indent + 2))
+
+    return "\n".join(parts)
+
+
+def _format_docstring(docstring: str, *, indent: int) -> str:
+    lines = docstring.splitlines()
+    prefix = " " * indent
+    result: list[str] = []
+    prev_blank = False
+    for line in lines:
+        stripped = line.rstrip()
+        if not stripped:
+            if not prev_blank:
+                result.append("")
+            prev_blank = True
+        else:
+            result.append(f"{prefix}{stripped}")
+            prev_blank = False
+    return "\n".join(result)
+
+
+def _is_private(name: str) -> bool:
+    return name.startswith("_")

api_squash/scanner.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+
+DEFAULT_SKIP_DIRS = {
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".git",
+    "node_modules",
+    ".tox",
+    ".eggs",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    "build",
+    "dist",
+}
+
+
+def scan_directory(
+    root: Path,
+    *,
+    exclude: list[str] | None = None,
+    max_depth: int | None = None,
+) -> list[Path]:
+    exclude = exclude or []
+    found: list[Path] = []
+    _walk(root, root, found, exclude, max_depth, depth=0)
+    found.sort()
+    return found
+
+
+def _walk(
+    root: Path,
+    current: Path,
+    found: list[Path],
+    exclude: list[str],
+    max_depth: int | None,
+    depth: int,
+) -> None:
+    if max_depth is not None and depth > max_depth:
+        return
+
+    try:
+        entries = sorted(current.iterdir())
+    except PermissionError:
+        return
+
+    for entry in entries:
+        relative = entry.relative_to(root).as_posix()
+
+        if entry.is_dir():
+            if entry.name in DEFAULT_SKIP_DIRS:
+                continue
+            if any(
+                fnmatch.fnmatch(relative, pat) or fnmatch.fnmatch(entry.name, pat)
+                for pat in exclude
+            ):
+                continue
+            _walk(root, entry, found, exclude, max_depth, depth + 1)
+        elif entry.is_file() and entry.suffix == ".py":
+            if any(fnmatch.fnmatch(relative, pat) for pat in exclude):
+                continue
+            found.append(entry)

api_squash-0.1.0.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: api-squash
+Version: 0.1.0
+Summary: Extract Python API surfaces in a compact, token-efficient format
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0

api_squash-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+api_squash/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+api_squash/cli.py,sha256=7mTPmqEOo3nasDa-w5oEXBYvTSfA1mVuRfcvr__acAI,2520
+api_squash/extractor.py,sha256=ArMBd1BjpEokt6OR8FqacNNtrw7TmaGiGrmEeZpsHhQ,3273
+api_squash/models.py,sha256=lJNI7wfQKlj8H9y49alLae_xk0RQaxm0NsjAn3VJXU8,543
+api_squash/renderer.py,sha256=ZRm3FjagIeYi0XuYg_gi5AgT4So8u-bzAfVUY9T_a-o,2689
+api_squash/scanner.py,sha256=_rUQJPJ33yI0ZCWfkVq3jp4-DTJJ8KFe-ljxunewMrg,1493
+api_squash-0.1.0.dist-info/METADATA,sha256=Y83EJ7L9IoQGreQ5H2UozvOlwBTAYHLclfMzBtA48bE,178
+api_squash-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+api_squash-0.1.0.dist-info/entry_points.txt,sha256=5MApuY0aDocok61Pcm6VHr7atM6UlmTNAn_bXwMfho4,50
+api_squash-0.1.0.dist-info/RECORD,,

api_squash-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

api_squash-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+api-squash = api_squash.cli:cli