Codebase

Main interface for codemods to interact with codebases, including utility methods etc..

Properties

---

classes

List of all Classes in the codebase

def classes(self) -> list[TClass]:
    ...

current_commit

The current commit checked out

def current_commit(self) -> GitCommit | None:
    ...

default_branch

The default branch of this repository

def default_branch(self) -> str:
    ...

directories

List of all Directories in the codebase

def directories(self) -> list[TDirectory]:
    ...

external_modules

List of all ExternalModules in the codebase

def external_modules(self) -> list[ExternalModule]:
    ...

files

List of all Files in the codebase. If it’s a Python codebase, this will return PyFiles (python files). If it’s a Typescript codebase, this will return TSFiles (typescript files). Does not include non-source files, such as markdown files, image files, etc. Use codebase.get_file to get a specific file by path, or use codebase.get_files() to get all files in the codebase.

def files(self) -> list[TSourceFile]:
    ...

functions

List of all Functions in the codebase

def functions(self) -> list[TFunction]:
    ...

global_vars

List of all GlobalVars in the codebase

def global_vars(self) -> list[TGlobalVar]:
    ...

imports

List of all Imports in the codebase

def imports(self) -> list[TImport]:
    ...

interfaces

List of all Interfaces in the codebase (Typescript only)

def interfaces(self) -> list[TInterface]:
    ...

symbols

List of all top-level Symbols (Classes, Functions, etc.) in the codebase. Excludes Class methods.

def symbols(self) -> list[TSymbol]:
    ...

types

List of all Types in the codebase (Typescript only)

def types(self) -> list[TTypeAlias]:
    ...

Methods

---

ai

Generates a response from the AI based on the provided prompt, target, and context.

This method sends a prompt to the AI client, optionally including a target and context to provide additional information. The AI processes the input and generates a response, which is then returned as a string.

By default, there is a maximum of 150 AI requests per codemod execution. You can change this limit by calling codebase.set_max_ai_requests with the number of requests you want to allow.

Args: prompt (str): The prompt to send to the AI. target (Editable | None): The target editable object for the AI request. context (Editable | list[Editable] | dict[str, Editable | list[Editable]] | None): The context for the AI request. model (str): The model to use for the AI request. Defaults to “gpt-4o-mini”.

Returns: str: The response generated by the AI.

Raises: MaxAIRequestsError: If the maximum number of AI requests is exceeded.

Example:

new_symbol = codebase.ai("Rewrite this to be more coherent.", target=symbol)
symbol.edit(new_symbol)

def ai(self, prompt: str, target: Editable | None = None, context: Editable | list[Editable] | dict[str, Editable | list[Editable]] | None = None, model: str = "gpt-4o-mini") -> str:
    ...

checkout

Discard changes, checkout a branch using git, then sync the codebase to the new branch.

Args: commit: Commit to checkout branch: Branch to checkout create_if_missing: If the branch doesn’t exist, create one remote: Try pulling a remote branch Examples:

codebase.checkout(branch=“branch”, create_if_missing=True)

def checkout(self, *, commit: str | GitCommit | None = None, branch: str | None = None, create_if_missing: bool = False, remote: bool = False) -> CheckoutResult:
    ...

commit

Commits all staged changes to the codebase. Must be called if you intend to have multiple overlapping edits on a single entity For example:

symbol = file.get_symbol('foo')
symbol.rename('bar')
symbol.commit()
sybmol.move_to_file('baz.py')
assert symbol.name == 'bar'  # This will fail if commit is not called

def commit(self, sync_graph: bool = True) -> None:
    ...

create_directory

Creates a directory at the specified dirpath

def create_directory(self, dir_path: str, exist_ok: bool = False, parents: bool = False) -> None:
    ...

create_file

Creates a file with specified content at specified filepath

def create_file(self, filepath: str, content: str = "", sync: bool = True) -> File:
    ...

flag_ai

Determines whether to flag the symbol, file, attribute, or message using AI.

Flagging returns either a Codeflag object or None. Use flag_ai when you want to conditionally flag an entity based on the AI’s response.

By default, there is a maximum of 150 AI requests per codemod execution. You can change this limit by calling codebase.set_max_ai_requests with the number of requests you want to allow.

Args: prompt (str): The prompt to send to the AI. target (Editable | None): The target editable object for the AI request. context (Editable | list[Editable] | dict[str, Editable | list[Editable]] | None): The context for the AI request.

Returns: CodeFlag | None: The flag object if the AI request should be flagged, otherwise None.

Raises: MaxAIRequestsError: If the maximum number of AI requests is exceeded.

Example:

if codebase.flag_ai("Should I flag this?", target=symbol):
symbol.flag()

def flag_ai(
        self, prompt: str, target: Editable | None = None, context: Editable | list[Editable] | dict[str, Editable | list[Editable]] | None = None, model: str = "gpt-4o-mini"
    ) -> CodeFlag | None:
    ...

flag_instance

Flags a symbol, file or import. This enables enhanced tracking of changes and splitting into smaller PRs, etc. Should be called once per flaggable entity and should be called before any edits are made to the entity.

def flag_instance(
        self,
        symbol: TSymbol | None = None,
        message: str | None = None,
        message_type: MessageType = MessageType.GITHUB,
        message_recipient: str | None = None,
    ) -> CodeFlag:
    ...

get_class

Returns a class that matches the given name. Raises ValueError if there are multiple.

def get_class(self, class_name: str, optional: bool = False) -> TClass | None:
    ...

get_directory

Returns Directory by dir_path, or full path to the directory from codebase root.

def get_directory(self, dir_path: str, optional: bool = False) -> TDirectory | None:
    ...

get_file

Returns SourceFile by filepath, or full path to the file from codebase root.

def get_file(self, filepath: str, optional: bool = False) -> File | None:
    ...

get_function

Returns a function that matches the given name. Raises ValueError if there are multiple.

def get_function(self, function_name: str, optional: bool = False) -> TFunction | None:
    ...

get_symbol

Returns Symbol by name. Raises ValueError if there are multiple

def get_symbol(self, symbol_name: str, optional: bool = False) -> TSymbol | None:
    ...

get_symbols

Optimized implementation to retrieve multiple symbols by the same name. Applies when there is a symbol without a unique name, in which case get_symbol will raise ValueError

def get_symbols(self, symbol_name: str) -> list[TSymbol]:
    ...

git_commit

Commits all staged changes to the codebase and git.

Returns: The commit hash if it was created

def git_commit(self, message: str, *, verify: bool = False, sync: bool = True) -> GitCommit | None:
    ...

has_directory

Returns True iff the directory exists in the codebase

def has_directory(self, dir_path: str) -> bool:
    ...

has_file

Returns True iff the file exists in the codebase

def has_file(self, filepath: str) -> bool:
    ...

has_symbol

Returns True iff the symbol exists in the codebase

def has_symbol(self, symbol_name: str) -> bool:
    ...

set_max_ai_requests

Sets the maximum number of AI requests. Hard limit capped at HARD_MAX_AI_LIMIT

Args: max_ai_requests (int | None): The maximum number of AI requests.

def set_max_ai_requests(self, max_ai_requests: int | None) -> None:
    ...

should_fix

Returns True if the flag should be fixed. This is used to filter out flags that are not in the active group.

def should_fix(self, flag: CodeFlag) -> bool:
    ...

visualize

Visualizes a NetworkX graph.

Args: G (Graph | go.Figure): A NetworkX DiGraph object root (Editable | str | int | None): The root node to visualize. Defaults to None.

Returns: None

def visualize(self, G: Graph | go.Figure, root: Editable | str | int | None = None) -> None:
    ...