Index System

The index system provides various implementations for storing and querying code symbols.

Base Classes

class code_index.index.base.BaseIndex

Bases: ABC

Abstract base class for code symbol indexes.

Encapsulates CRUD operations and storage for a codebase index containing function and method definitions and references. Provides a unified interface for different index implementations.

__str__() → str

Returns a string representation of the index.

Returns:

A compact summary of the index contents.

abstractmethod add_definition(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], definition: Definition)

Adds a function or method definition to the index.

Parameters:

• func_like – The function or method information.

• definition – The definition details including location and context.

abstractmethod add_reference(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], reference: Reference)

Adds a function or method reference to the index.

Parameters:

• func_like – The function or method information.

• reference – The reference details including location and context.

abstractmethod __len__() → int

Returns the number of function-like items in the index.

Returns:

The count of indexed functions and methods.

abstractmethod __getitem__(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]) → FunctionLikeInfo

Gets function information from the index.

Parameters:

func_like – The function or method to retrieve.

Returns:

The function information if found.

Raises:

KeyError – If the function is not found in the index.

abstractmethod __setitem__(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], info: FunctionLikeInfo)

Sets function information in the index.

Parameters:

• func_like – The function or method key.

• info – The function information to store.

abstractmethod __delitem__(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')])

Deletes function information from the index.

Parameters:

func_like – The function or method to remove.

abstractmethod __contains__(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]) → bool

Checks if function exists in the index.

Parameters:

func_like – The function or method to check.

Returns:

True if the function exists in the index, False otherwise.

abstractmethod __iter__() → Iterator[Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]]

Iterates over all functions in the index.

Returns:

An iterator of Symbol objects.

abstractmethod update(mapping: dict[Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], FunctionLikeInfo])

Updates the index with multiple function entries.

Parameters:

mapping – A dictionary mapping functions to their information.

abstractmethod items() → Iterable[tuple[Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], FunctionLikeInfo]]

Gets all items in the index as key-value pairs.

Returns:

An iterable of (Symbol, FunctionLikeInfo) tuples.

abstractmethod get_info(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]) → FunctionLikeInfo | None

Gets function information from the index.

Parameters:

func_like – The function or method to retrieve.

Returns:

The function information if found, None otherwise.

abstractmethod get_definitions(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]) → Iterable[Definition]

Gets all definitions for a function from the index.

Parameters:

func_like – The function or method to retrieve definitions for.

Returns:

An iterable of Definition objects.

abstractmethod get_references(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]) → Iterable[Reference]

Gets all references for a function from the index.

Parameters:

func_like – The function or method to retrieve references for.

Returns:

An iterable of PureReference objects.

find_full_definition(pure_definition: PureDefinition) → tuple[Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], Definition] | None

Find the full Definition given a PureDefinition.

This attempts to resolve which symbol (function/method) owns the given PureDefinition and returns the corresponding full Definition along with its owning symbol if found.

Notes

• A PureDefinition may belong to exactly one symbol or to none.

• Implementations SHOULD return None when no owning symbol is found.

Parameters:

pure_definition – The fingerprint of a definition (location only).

Returns:

A tuple of (symbol, definition) if resolved, otherwise None.

abstractmethod as_data() → IndexData

Converts the index to a serializable data format.

Returns:

A dictionary representation of the index data.

abstractmethod update_from_data(data: IndexData)

Updates the index with data from a serialized format.

Parameters:

data – A dictionary containing function information to load.

persist_to(path: Path, save_strategy: PersistStrategy)

Persists the index data to a file.

Parameters:

• path – The file path to save the index data.

• save_strategy – The persistence strategy to use for saving.

classmethod load_from(path: Path, load_strategy: PersistStrategy) → BaseIndex

Loads index data from a file and creates a new index instance.

Parameters:

• path – The file path to load the index data from.

• load_strategy – The persistence strategy to use for loading.

Returns:

A new BaseIndex instance with the loaded data.

abstractmethod handle_query(query: QueryByKey | QueryByName | QueryByNameRegex | QueryFullDefinition) → list[CodeQuerySingleResponse]

Handles a query against the index.

Parameters:

query – The query to execute against the index.

Returns:

An iterable of CodeQuerySingleResponse containing query results.

class code_index.index.base.PersistStrategy

Bases: ABC

Abstract base class for persistence strategies.

Defines the interface for saving and loading index data to/from persistent storage. Implementations can support various formats like JSON, SQLite, etc.

__init__()

Initialize the persist strategy.

abstractmethod __repr__() → str

Returns a string representation of the persist strategy.

Returns:

A compact summary of the strategy configuration.

abstractmethod save(data: IndexData, path: Path)

Saves index data to the specified path.

Parameters:

• data – The index data to save.

• path – The file path where data will be saved.

abstractmethod load(path: Path) → IndexData

Loads index data from the specified path.

Parameters:

path – The file path from which to load data.

Returns:

The loaded index data.

Query Interface

Query interfaces for searching code symbols in the index.

This module defines various query types to search for functions and methods in the code index. It includes exact key matches, name-based searches, and regex-based searches.

class code_index.index.code_query.QueryByKey(*, func_like: Function | Method)

Bases: BaseModel

Query for exact function or method matches by key.

This query type returns exact matches in the index using the complete function or method signature as the key.

Examples

Query a function: QueryByKey(func_like=Function(name=”my_function”)) Query a method: QueryByKey(func_like=Method(name=”my_method”, class_name=”MyClass”)) Query unbound method: QueryByKey(func_like=Method(name=”my_method”, class_name=None))

func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]

The function or method to search for exactly.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class code_index.index.code_query.FilterOption(*values)

Bases: Enum

Filter options for symbol types in queries.

FUNCTION = 'function'

Filter for standalone functions only.

METHOD = 'method'

Filter for class methods only.

ALL = 'all'

Include both functions and methods in results.

class code_index.index.code_query.QueryByName(*, name: str, type_filter: FilterOption = FilterOption.ALL)

Bases: BaseModel

Query for functions and methods by name with optional type filtering.

Finds all symbols with the specified name, optionally filtered by type. This is useful for finding all occurrences of symbols with the same name.

Examples

Query functions: QueryByName(name=”my_function”, type_filter=FilterOption.FUNCTION) Query methods: QueryByName(name=”my_method”, type_filter=FilterOption.METHOD) Query all symbols: QueryByName(name=”my_symbol”, type_filter=FilterOption.ALL)

name: str

The exact name of the function or method to search for.

type_filter: FilterOption

The type of symbols to include in results. Defaults to ALL.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class code_index.index.code_query.QueryByNameRegex(*, name_regex: str, type_filter: FilterOption = FilterOption.ALL)

Bases: BaseModel

Query for functions and methods by regex name pattern with optional type filtering.

Finds all symbols whose names match the specified regex pattern, optionally filtered by type. This is useful for pattern-based searches.

Examples

Query test functions: QueryByNameRegex(name_regex=r”^test_.*”, type_filter=FilterOption.FUNCTION) Query handler methods: QueryByNameRegex(name_regex=r”.*_handler$”, type_filter=FilterOption.METHOD) Query debug symbols: QueryByNameRegex(name_regex=r”.*debug.*”, type_filter=FilterOption.ALL)

name_regex: str

The regex pattern to match function or method names.

type_filter: FilterOption

The type of symbols to include in results. Defaults to ALL.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class code_index.index.code_query.QueryFullDefinition(*, symbol: Function | Method, pure_definition: PureDefinition)

Bases: BaseModel

Given a symbol and a location, return the full definition of that symbol.

This is useful for navigating to the complete definition of a symbol from a specific location in the codebase.

The result of this query (the FunctionLikeInfo) will only contain the corresponding Definition that matches the provided PureDefinition. If there is no match, the result will be empty.

symbol: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]

The function or method symbol to look up.

pure_definition: PureDefinition

The specific location in the codebase to find the full definition from.

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

code_index.index.code_query.CodeQuery = code_index.index.code_query.QueryByKey | code_index.index.code_query.QueryByName | code_index.index.code_query.QueryByNameRegex | code_index.index.code_query.QueryFullDefinition

Represents a query for code symbols in the index.

class code_index.index.code_query.CodeQuerySingleResponse(*, func_like: Function | Method, info: FunctionLikeInfo)

Bases: BaseModel

Represents a single response from a code query.

Contains the function or method information along with its associated definitions and references from the index.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]

The function or method that matched the query.

info: FunctionLikeInfo

The complete information about the function or method, including definitions and references.

class code_index.index.code_query.CodeQueryResponse(*, results: list[~code_index.index.code_query.CodeQuerySingleResponse] = <factory>)

Bases: BaseModel

Represents the response for a code query.

Contains a list of results matching the query criteria.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

results: list[CodeQuerySingleResponse]

List of matching function or method information.

Index Implementations

class code_index.index.impl.simple_index.SimpleIndex

Bases: BaseIndex

A simple in-memory implementation of the BaseIndex.

Stores all index data in memory using a dictionary. This implementation is suitable for small to medium-sized codebases where fast access and simplicity are preferred over memory efficiency.

data

Internal dictionary storing function/method information.

__init__()

Initializes an empty SimpleIndex.

__repr__()

Returns a detailed string representation of the index.

add_definition(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], definition: Definition)

Adds a function or method definition to the index.

Parameters:

• func_like – The function or method information.

• definition – The definition details including location and context.

add_reference(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], reference: Reference)

Adds a function or method reference to the index.

Parameters:

• func_like – The function or method information.

• reference – The reference details including location and context.

get_info(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]) → FunctionLikeInfo | None

Gets function information from the index.

Parameters:

func_like – The function or method to retrieve.

Returns:

The function information if found, None otherwise.

get_definitions(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]) → Iterable[Definition]

Gets all definitions for a function from the index.

Parameters:

func_like – The function or method to retrieve definitions for.

Returns:

An iterable of Definition objects.

get_references(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]) → Iterable[Reference]

Gets all references for a function from the index.

Parameters:

func_like – The function or method to retrieve references for.

Returns:

An iterable of PureReference objects.

items() → Iterable[tuple[Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], FunctionLikeInfo]]

Gets all items in the index as key-value pairs.

Returns:

An iterable of (Symbol, FunctionLikeInfo) tuples.

update(mapping: dict[Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], FunctionLikeInfo])

Updates the index with multiple function entries.

Parameters:

mapping – A dictionary mapping functions to their information.

as_data() → IndexData

Converts the index to a serializable data format.

Returns:

A dictionary representation of the index data.

update_from_data(data: IndexData)

Updates the index with data from a serialized format.

Parameters:

data – A dictionary containing function information to load.

static _type_filterer(func_like: Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], filter_option: FilterOption) → bool

Filters function-like objects based on type criteria.

Parameters:

• func_like – The function or method to filter.

• filter_option – The filter criteria to apply.

Returns:

True if the function matches the filter criteria, False otherwise.

handle_query(query: QueryByKey | QueryByName | QueryByNameRegex | QueryFullDefinition) → list[CodeQuerySingleResponse]

Processes a query against the index and returns matching results.

Parameters:

query – The query to execute against the index.

Returns:

An iterable of CodeQuerySingleResponse containing all matches.

Raises:

ValueError – If the query type is unsupported or regex pattern is invalid.

find_full_definition(pure_definition: PureDefinition) → tuple[Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')], Definition] | None

Linear scan over all symbols/definitions to locate a full definition.

Parameters:

pure_definition – The fingerprint of a definition to locate.

Returns:

(symbol, definition) if found; otherwise None.

Persistence Backends

Implementation of persistence mechanisms for the code index module.

This module provides different strategies to persist the indexed data. The available strategies include JSON (dumping to a single JSON file) and SQLite (storing data in a SQLite database).

class code_index.index.persist.SingleJsonFilePersistStrategy

Bases: PersistStrategy

JSON file persistence strategy for index data.

Saves and loads index data to/from a single JSON file using custom serialization for dataclass objects and complex types.

__init__()

Initializes the JSON persistence strategy.

__repr__() → str

Returns a string representation of the persistence strategy.

save(data: IndexData, path: Path)

Saves index data to a JSON file.

Parameters:

• data – The index data object to save.

• path – The file path where data will be saved.

Raises:

• ValueError – If path is a directory or parent directory issues.

• FileNotFoundError – If parent directory doesn’t exist.

• RuntimeError – If saving fails due to other errors.

load(path: Path) → IndexData

Loads index data from a JSON file.

Parameters:

path – The JSON file path to load from.

Returns:

The loaded index data.

Raises:

• FileNotFoundError – If the file doesn’t exist.

• ValueError – If path is a directory or not a regular file.

• json.JSONDecodeError – If file is not valid JSON.

• RuntimeError – If loading fails due to other errors.

class code_index.index.persist.SqlitePersistStrategy

Bases: PersistStrategy

SQLite database persistence strategy for index data.

Stores index data in a SQLite database with proper relational structure. Supports both file-based and in-memory databases.

__init__()

Initializes the SQLite persistence strategy.

__repr__()

Returns a string representation of the persistence strategy.

get_engine(path: Path | None = None, make_empty_db: bool = False)

Gets the SQLite database engine.

Parameters:

• path – Database file path. If None, uses in-memory database.

• make_empty_db – If True, removes existing database file if it exists.

Returns:

SQLAlchemy engine for the database.

static _location_as_criteria(location: CodeLocation) → dict

将 CodeLocation 转换为查询条件字典。

save(data: IndexData, path: Path)

将索引数据保存到 SQLite 数据库。

Parameters:

• data – 要保存的索引数据字典

• path – 保存数据库文件的路径

static _make_function_like(symbol_db: OrmSymbol) → Annotated[Function | Method, FieldInfo(annotation=NoneType, required=True, description='Discriminated union for function-like entities.', discriminator='type')]

根据 OrmSymbol 创建 Symbol 对象。

_load(session: Session) → IndexData

从 SQLAlchemy 会话中加载索引数据。

Parameters:

session – SQLAlchemy 会话对象

Returns:

IndexData 对象

load(path: Path) → IndexData

从 SQLite 数据库加载索引数据。

Parameters:

path – SQLite 数据库文件的路径

Returns:

IndexData 对象