skim-python 0.0.1__py3-none-any.whl

skim_py/__init__.py

@@ -0,0 +1,5 @@
+"""skim_py package root."""
+
+from .cli import main
+
+__all__ = ["main"]

skim_py/block.py

@@ -0,0 +1,150 @@
+"""block subcommand implementation for skim-py."""
+
+from __future__ import annotations
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from .types import OutlineItem, ParsedFile
+from .parser import parse_source_file
+
+
+def collect_all_items(items: List[OutlineItem]) -> List[OutlineItem]:
+    res: List[OutlineItem] = []
+    for it in items:
+        res.append(it)
+        if it.children:
+            res.extend(collect_all_items(it.children))
+    return res
+
+
+def run_block(
+    file_path: str,
+    target: str,
+    raw: bool = False,
+    include_tests: bool = False,
+) -> int:
+    p = Path(file_path)
+    if not p.exists():
+        sys.stderr.write(f"Error: file not found: {file_path}\n")
+        return 1
+
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+            content = f.read()
+    except Exception as err:
+        sys.stderr.write(f"Error reading {file_path}: {err}\n")
+        return 1
+
+    parsed = parse_source_file(file_path, content, include_tests=include_tests)
+    all_items = collect_all_items(parsed.items)
+
+    matches: List[OutlineItem] = []
+
+    if "." in target:
+        dot_idx = target.index(".")
+        parent_target = target[:dot_idx]
+        child_target = target[dot_idx + 1 :]
+
+        parent_candidates = [it for it in all_items if it.parent_name is not None]
+
+        # Tier 1: Exact case match on both parent and child
+        exact_matches = [
+            it
+            for it in parent_candidates
+            if it.parent_name == parent_target and it.name == child_target
+        ]
+
+        if exact_matches:
+            matches = exact_matches
+        else:
+            # Tier 2: Case-insensitive match on both parent and child
+            p_lower = parent_target.lower()
+            c_lower = child_target.lower()
+            case_matches = [
+                it
+                for it in parent_candidates
+                if it.parent_name.lower() == p_lower and it.name.lower() == c_lower
+            ]
+
+            if case_matches:
+                matches = case_matches
+            else:
+                # Tier 3: Substring search
+                matches = [
+                    it
+                    for it in parent_candidates
+                    if p_lower in it.parent_name.lower()
+                    and (c_lower in it.name.lower() or c_lower in it.raw_header.lower())
+                ]
+    else:
+        # Standalone identifier
+        # Tier 1: Exact match on name
+        exact_matches = [it for it in all_items if it.name == target]
+
+        if exact_matches:
+            matches = exact_matches
+        else:
+            # Tier 2: Case-insensitive match on name
+            t_lower = target.lower()
+            case_matches = [it for it in all_items if it.name.lower() == t_lower]
+
+            if case_matches:
+                matches = case_matches
+            else:
+                # Tier 3: Case-insensitive substring match
+                matches = [
+                    it
+                    for it in all_items
+                    if t_lower in it.name.lower() or t_lower in it.raw_header.lower()
+                ]
+
+    cwd = os.getcwd()
+    try:
+        rel_path = os.path.relpath(file_path, cwd)
+    except ValueError:
+        rel_path = file_path
+
+    if not matches:
+        sys.stderr.write(f"Error: block '{target}' not found in {rel_path}\n")
+        return 2
+
+    if len(matches) > 1:
+        sys.stderr.write(
+            f"Error: ambiguous target '{target}' matched {len(matches)} candidates in {rel_path}:\n"
+        )
+        for idx, m in enumerate(matches, 1):
+            span = f"L{m.start_line}-L{m.end_line}".ljust(10)
+            sys.stderr.write(f"  {idx}) {span} {m.kind} {m.qualified_name}\n")
+        sys.stderr.write(
+            "\nTip: Disambiguate with Class.method (e.g. BaseModel.model_dump) or read line range directly.\n"
+        )
+        return 3
+
+    chosen = matches[0]
+    src_lines = content.splitlines()
+    block_lines = src_lines[chosen.start_line - 1 : chosen.end_line]
+
+    # Check for syntax errors within block range
+    block_errors = [
+        e for e in parsed.syntax_errors if chosen.start_line <= e.line <= chosen.end_line
+    ]
+
+    error_tag = ""
+    if block_errors:
+        n = len(block_errors)
+        error_tag = " [! 1 syntax error]" if n == 1 else f" [! {n} syntax errors]"
+
+    if raw:
+        print("\n".join(block_lines))
+    else:
+        print(f"=== {rel_path} (L{chosen.start_line}-L{chosen.end_line}){error_tag} ===")
+        for err in block_errors:
+            print(f"  Syntax Notice: L{err.line}: {err.message}")
+        for idx, line in enumerate(block_lines):
+            line_num = chosen.start_line + idx
+            line_padded = str(line_num).rjust(5)
+            print(f"{line_padded} | {line}")
+
+    return 0

skim_py/cli.py

@@ -0,0 +1,147 @@
+"""CLI entrypoint for skim-py."""
+
+from __future__ import annotations
+import sys
+import argparse
+from typing import List, Optional
+
+from .glance import run_glance
+from .block import run_block
+
+
+USAGE_DOC = """\
+skim-py: Fast Python outline & block extractor without test bloat.
+Prefer this over reading entire .py files to preserve token context.
+
+Usage:
+  skim-py glance [options] <path>...
+  skim-py block  [options] <file> <target>
+
+glance:
+  Outline structure, signatures, and line ranges across files/directories.
+
+  Usage:
+    skim-py glance [options] <path>...
+
+  Arguments:
+    <path>...                 One or more source files, directories, or globs
+
+  Options:
+    -s, --signatures          Show declarations & types without function bodies
+    -d, --details             Show class attributes, annotated fields, and enum members
+    -u, --uses, --imports     Display top-level import statements
+    -f, --filter <text>       Filter items containing <text> (case-insensitive, repeatable)
+    -t, --include-tests       Include test files (test_*.py, etc.) and test blocks
+
+  Examples:
+    skim-py glance src/models.py
+    skim-py glance src/ -s -u
+    skim-py glance src/ -s -f "BaseModel"
+
+block:
+  Extract verbatim code block for a class, method, function, or variable.
+
+  Usage:
+    skim-py block [options] <file> <target>
+
+  Arguments:
+    <file>                    Path to the source file
+    <target>                  Name of class, method, function, or Class.method
+
+  Options:
+    -t, --include-tests       Search inside test files and test blocks
+    --raw                     Omit line number gutter
+
+  Examples:
+    skim-py block src/models.py BaseModel
+    skim-py block src/models.py BaseModel.model_dump
+    skim-py block src/models.py BaseModel.model_dump --raw
+
+  Disambiguation:
+    If multiple items match, qualify Class.method (e.g. BaseModel.model_dump) or read line range directly.
+
+Agent Operational Workflow:
+  1. Glance first:   skim-py glance <path> -s
+  2. Locate logic:   skim-py glance <path> -f <keyword>
+  3. Inspect code:   Use `block <file> <Class.method>`, or read reported line spans (Lxx-Lyy)
+"""
+
+
+def main(args: Optional[List[str]] = None) -> int:
+    if args is None:
+        args = sys.argv[1:]
+
+    if not args or args[0] in {"-h", "--help"}:
+        sys.stdout.write(USAGE_DOC)
+        return 0
+
+    subcommand = args[0]
+
+    if subcommand == "glance":
+        parser = argparse.ArgumentParser(
+            prog="skim-py glance",
+            description="Outline structure, signatures, and line spans.",
+            add_help=False,
+        )
+        parser.add_argument("-s", "--signatures", action="store_true")
+        parser.add_argument("-d", "--details", action="store_true")
+        parser.add_argument("-u", "--uses", "--imports", action="store_true", dest="uses")
+        parser.add_argument("-f", "--filter", action="append", default=[], dest="filter")
+        parser.add_argument("-t", "--include-tests", action="store_true", dest="include_tests")
+        parser.add_argument("-h", "--help", action="store_true")
+        parser.add_argument("targets", nargs="*")
+
+        parsed_args, extra = parser.parse_known_args(args[1:])
+        if parsed_args.help:
+            sys.stdout.write(USAGE_DOC)
+            return 0
+        if not parsed_args.targets:
+            sys.stderr.write("Error: missing target path(s) for glance.\n")
+            return 1
+
+        return run_glance(
+            targets=parsed_args.targets,
+            signatures=parsed_args.signatures,
+            details=parsed_args.details,
+            uses=parsed_args.uses,
+            filters=parsed_args.filter,
+            include_tests=parsed_args.include_tests,
+        )
+
+    elif subcommand == "block":
+        parser = argparse.ArgumentParser(
+            prog="skim-py block",
+            description="Extract verbatim code block.",
+            add_help=False,
+        )
+        parser.add_argument("-t", "--include-tests", action="store_true", dest="include_tests")
+        parser.add_argument("--raw", action="store_true")
+        parser.add_argument("-h", "--help", action="store_true")
+        parser.add_argument("positionals", nargs="*")
+
+        parsed_args, extra = parser.parse_known_args(args[1:])
+        if parsed_args.help:
+            sys.stdout.write(USAGE_DOC)
+            return 0
+        if len(parsed_args.positionals) < 2:
+            sys.stderr.write("Error: block requires <file> and <target> arguments.\n")
+            return 1
+
+        file_path = parsed_args.positionals[0]
+        target = parsed_args.positionals[1]
+
+        return run_block(
+            file_path=file_path,
+            target=target,
+            raw=parsed_args.raw,
+            include_tests=parsed_args.include_tests,
+        )
+
+    else:
+        sys.stderr.write(f"Error: unknown subcommand '{subcommand}'. Use 'glance' or 'block'.\n\n")
+        sys.stdout.write(USAGE_DOC)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skim_py/glance.py

@@ -0,0 +1,203 @@
+"""glance subcommand implementation for skim-py."""
+
+from __future__ import annotations
+import os
+import sys
+import glob
+from pathlib import Path
+from typing import List, Optional
+
+from .types import OutlineItem, ParsedFile
+from .parser import parse_source_file, is_test_file
+
+
+IGNORED_DIRS = {
+    ".git",
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".venv",
+    "venv",
+    "env",
+    "node_modules",
+    "dist",
+    "build",
+    ".tox",
+    ".eggs",
+}
+
+SUPPORTED_EXTS = {".py", ".pyi"}
+
+
+def is_supported_file(path_str: str) -> bool:
+    return Path(path_str).suffix.lower() in SUPPORTED_EXTS
+
+
+def find_files_recursively(dir_path: str, include_tests: bool) -> List[str]:
+    results: List[str] = []
+    try:
+        with os.scandir(dir_path) as it:
+            for entry in it:
+                if entry.is_dir(follow_symlinks=False):
+                    if entry.name in IGNORED_DIRS:
+                        continue
+                    if not include_tests and entry.name.lower() in {"tests", "test", "testing", "__tests__"}:
+                        continue
+                    results.extend(find_files_recursively(entry.path, include_tests))
+                elif entry.is_file(follow_symlinks=False):
+                    if is_supported_file(entry.name):
+                        if not include_tests and is_test_file(entry.path):
+                            continue
+                        results.append(entry.path)
+    except (PermissionError, FileNotFoundError) as err:
+        sys.stderr.write(f"Warning: error reading directory {dir_path}: {err}\n")
+    return results
+
+
+def collect_files(targets: List[str], include_tests: bool) -> List[str]:
+    files: List[str] = []
+    for target in targets:
+        p = Path(target)
+        if p.exists():
+            if p.is_dir():
+                files.extend(find_files_recursively(str(p), include_tests))
+            elif p.is_file():
+                if is_supported_file(str(p)):
+                    # When an explicit file path is directly supplied, always include it
+                    files.append(str(p))
+        elif any(char in target for char in "*?[]"):
+            matches = glob.glob(target, recursive=True)
+            for m in matches:
+                if is_supported_file(m):
+                    if include_tests or not is_test_file(m):
+                        files.append(m)
+        else:
+            sys.stderr.write(f"Warning: path not found: {target}\n")
+
+    unique = sorted(set(os.path.normpath(f) for f in files))
+    return unique
+
+
+def item_matches_filters(item: OutlineItem, content: str, lines: List[str], filters: List[str]) -> bool:
+    if not filters:
+        return True
+    block_text = "\n".join(lines[item.start_line - 1 : item.end_line]).lower()
+    return all(f.lower() in block_text for f in filters)
+
+
+def has_child_matching(item: OutlineItem, content: str, lines: List[str], filters: List[str]) -> bool:
+    if not filters:
+        return True
+    for ch in item.children:
+        if item_matches_filters(ch, content, lines, filters) or has_child_matching(ch, content, lines, filters):
+            return True
+    return False
+
+
+def run_glance(
+    targets: List[str],
+    signatures: bool = False,
+    details: bool = False,
+    uses: bool = False,
+    filters: Optional[List[str]] = None,
+    include_tests: bool = False,
+) -> int:
+    filters = filters or []
+    files = collect_files(targets, include_tests)
+
+    if not files:
+        sys.stderr.write("Error: no Python files found matching input.\n")
+        return 1
+
+    printed_count = 0
+    cwd = os.getcwd()
+
+    for file_path in files:
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+                content = f.read()
+        except Exception as err:
+            sys.stderr.write(f"Error reading {file_path}: {err}\n")
+            continue
+
+        src_lines = content.splitlines()
+        parsed = parse_source_file(file_path, content, include_tests=include_tests)
+
+        if filters:
+            has_match = any(
+                item_matches_filters(it, content, src_lines, filters)
+                or has_child_matching(it, content, src_lines, filters)
+                for it in parsed.items
+            )
+            if not has_match and not parsed.syntax_errors:
+                continue
+
+        if printed_count > 0:
+            print("\n" + "=" * 70 + "\n")
+        printed_count += 1
+
+        test_info = ""
+        if parsed.is_test_file and include_tests:
+            test_info = " [test]"
+        elif parsed.test_ranges and not include_tests:
+            tr_desc = ", ".join(f"{s}..{e}" for s, e in parsed.test_ranges)
+            test_info = f" [tests skipped: {tr_desc}]"
+
+        error_tag = ""
+        if parsed.syntax_errors:
+            n = len(parsed.syntax_errors)
+            error_tag = " [! 1 syntax error]" if n == 1 else f" [! {n} syntax errors]"
+
+        try:
+            rel_path = os.path.relpath(file_path, cwd)
+        except ValueError:
+            rel_path = file_path
+
+        print(f"=== {rel_path} ({parsed.total_lines} lines){test_info}{error_tag} ===")
+
+        for err in parsed.syntax_errors:
+            print(f"  Syntax Notice: L{err.line}: {err.message}")
+
+        if uses:
+            if parsed.imports:
+                print("\nImports:")
+                for imp in parsed.imports:
+                    for line in imp.splitlines():
+                        print(f"  {line}")
+            else:
+                print("\nImports: (none)")
+
+        print("\nOutline:")
+
+        def render_tree(items: List[OutlineItem], depth: int = 0) -> None:
+            for it in items:
+                matches = item_matches_filters(it, content, src_lines, filters)
+                child_matches = has_child_matching(it, content, src_lines, filters)
+                if not matches and not child_matches:
+                    continue
+
+                span = f"L{it.start_line}-L{it.end_line}"
+                if it.kind == "test":
+                    label = it.raw_header
+                elif signatures:
+                    label = it.raw_header
+                else:
+                    label = f"{it.kind} {it.name}"
+
+                child_indent = "  " * depth
+                span_padded = span.ljust(12)
+                print(f"  {span_padded} {child_indent}{label}")
+
+                if it.fields_or_variants and details:
+                    f_indent = " " * (17 + depth * 2)
+                    for fv in it.fields_or_variants:
+                        print(f"{f_indent}| {fv}")
+
+                methods_or_subitems = [ch for ch in it.children if ch.kind in {"method", "test"}]
+                if methods_or_subitems:
+                    render_tree(methods_or_subitems, depth + 1)
+
+        render_tree(parsed.items)
+
+    return 0