Skip to content

api-reference.md

Latest commit

 

History

History
303 lines (237 loc) · 6 KB

api-reference.md

File metadata and controls

303 lines (237 loc) · 6 KB
Raw

API Reference

CodeLens

Main entry point. Manages parser lifecycle and language registration.

from pylens import CodeLens

lens = CodeLens(languages: list[str] | None = None)

Parameters:

  • languages — optional list of language names to register. If None, all 7 built-in languages are registered.

Properties:

  • supported_languages: list[str] — list of registered language names.

get_symbols(path)

def get_symbols(self, path: str | Path) -> FileOutline

Extract all symbols (functions, classes, methods) from a single file.

Returns: FileOutline

@dataclass
class FileOutline:
    path: str
    language: str
    symbols: list[Symbol]
    imports: list[Import]
    symbol_count: int  # @property

@dataclass
class Symbol:
    name: str
    kind: Literal["function", "class", "method", "variable", "constant", "type", "interface", "module"]
    line: int
    signature: str | None
    docstring: str | None
    parent: str | None  # enclosing class name

@dataclass
class Import:
    module: str
    names: list[str]
    line: int

get_references(symbol, root_path, definition_file, definition_line)

def get_references(
    self,
    symbol: str,
    root_path: str | Path,
    definition_file: str | Path,
    definition_line: int,
) -> ReferencesResult

Find all usages of a symbol across a codebase.

Returns: ReferencesResult

@dataclass
class ReferencesResult:
    symbol: str
    definition: Reference | None
    references: list[Reference]
    total: int  # @property

@dataclass
class Reference:
    file: str
    line: int
    context: str
    kind: Literal["definition", "call", "import", "attribute"]

get_outline(root_path, max_depth=3)

def get_outline(self, root_path: str | Path, max_depth: int = 3) -> OutlineNode

Get a recursive directory tree with per-file symbol summaries.

Returns: OutlineNode

@dataclass
class OutlineNode:
    name: str
    path: str
    is_dir: bool
    children: list[OutlineNode]
    symbols: list[Symbol] | None  # None for directories
    symbol_count: int  # @property — recursive sum

get_import_graph(root_path)

def get_import_graph(self, root_path: str | Path) -> ImportGraphResult

Build a full import graph: who imports what, who is imported by whom.

Returns: ImportGraphResult

@dataclass
class ImportGraphResult:
    root_path: str
    imports: dict[str, list[ImportEdge]]
    imported_by: dict[str, list[ImportedBy]]
    stats: ImportGraphStats

@dataclass
class ImportEdge:
    imported: str
    resolved_path: str | None
    names: list[str]
    kind: Literal["local", "stdlib", "third_party", "relative", "unresolved"]
    line: int

@dataclass
class ImportedBy:
    importer: str
    names: list[str]
    line: int

@dataclass
class ImportGraphStats:
    total_files: int
    total_imports: int
    local: int
    stdlib: int
    third_party: int
    relative: int
    unresolved: int
    most_imported: list[tuple[str, int]]
    most_imports: list[tuple[str, int]]
    orphan_files: list[str]

get_call_graph(symbol, file_path, definition_line)

def get_call_graph(
    self,
    symbol: str,
    file_path: str | Path,
    definition_line: int,
) -> CallGraphResult

Find all functions called by a given function (callees only).

Returns: CallGraphResult

@dataclass
class CallGraphResult:
    symbol: str
    file: str
    line: int
    kind: str
    callees: list[Callee]
    unresolved: list[Callee]

@dataclass
class Callee:
    name: str
    line: int
    resolved_file: str | None
    resolved_line: int | None
    resolved_kind: str | None
    module_hint: str | None

get_test_coverage(source_file, root_path)

def get_test_coverage(
    self,
    source_file: str | Path,
    root_path: str | Path,
) -> TestCoverageResult

Find test files for a source file and match test functions to source symbols.

Returns: TestCoverageResult

@dataclass
class TestCoverageResult:
    source_file: str
    test_files: list[str]
    covered_symbols: list[str]
    uncovered_symbols: list[str]
    coverage: Literal["full", "partial", "none"]

get_type_hierarchy(root_path)

def get_type_hierarchy(self, root_path: str | Path) -> TypeHierarchyResult

Build a class inheritance graph across the entire codebase.

Returns: TypeHierarchyResult

@dataclass
class TypeHierarchyResult:
    root_path: str
    types: dict[str, TypeNode]
    roots: list[str]

@dataclass
class TypeNode:
    name: str
    file: str
    line: int
    bases: list[str]
    subclasses: list[str]
    is_abstract: bool

find_similar(symbol, file_path, definition_line, root_path, max_results=10)

def find_similar(
    self,
    symbol: str,
    file_path: str | Path,
    definition_line: int,
    root_path: str | Path,
    max_results: int = 10,
) -> FindSimilarResult

Find structurally similar functions via AST fingerprinting.

Returns: FindSimilarResult

@dataclass
class FindSimilarResult:
    query_symbol: str
    query_file: str
    query_line: int
    results: list[SimilarFunction]

@dataclass
class SimilarFunction:
    name: str
    file: str
    line: int
    kind: str
    signature: str | None
    similarity: float

Determinism Guarantees

Operation Deterministic Notes
get_symbols ✅ Yes Pure AST extraction
get_references ⚠️ Partial Within-file: yes. Cross-file: grep with AST filtering
get_outline ✅ Yes File system walk + AST extraction
get_import_graph ✅ Yes AST extraction + mechanical path resolution
get_call_graph ✅ Yes Callees only. Same-file resolution via AST
get_test_coverage ⚠️ Partial File matching is heuristic. Symbol matching is exact
get_type_hierarchy ✅ Yes Pure AST extraction
find_similar ✅ Yes Same codebase → same similarity scores