insert_before_symbol

Inserts content before a symbol's definition in code files to add classes, functions, imports, or other elements at specific locations.

Instructions

Inserts the given body/content before the beginning of the definition of the given symbol (via the symbol's location). A typical use case is to insert a new class, function, method, field or variable assignment. It also can be used to insert a new import statement before the first symbol in the file.

Input Schema

TableJSON Schema

Name	Required	Description
`name_path`	Yes	Name path of the symbol before which to insert content (definitions in the `find_symbol` tool apply).
`relative_path`	Yes	The relative path to the file containing the symbol.
`body`	Yes	The body/content to be inserted before the line in which the referenced symbol is defined.

Implementation Reference

src/serena/symbol.py:809-823 (handler)

Main entry point (handler) for the 'insert_before_symbol' tool. Finds the symbol by name and file, then delegates to the low-level insertion method.

def insert_before_symbol(self, name_path: str, relative_file_path: str, body: str, *, use_same_indentation: bool = True) -> None:
    """
    Inserts content before the symbol with the given name in the given file.
    """
    symbol_candidates = self.find_by_name(name_path, within_relative_path=relative_file_path)
    if len(symbol_candidates) == 0:
        raise ValueError(f"No symbol with name {name_path} found in file {relative_file_path}")
    if len(symbol_candidates) > 1:
        raise ValueError(
            f"Found multiple {len(symbol_candidates)} symbols with name {name_path} in file {relative_file_path}. "
            f"May be an overwritten variable, in which case you can ignore this error. Proceeding with the first one. "
            f"Found symbols at locations: \n" + json.dumps([s.location.to_dict() for s in symbol_candidates], indent=2)
        )
    symbol = symbol_candidates[0]
    self.insert_before_symbol_at_location(symbol.location, body, use_same_indentation=use_same_indentation)

src/serena/symbol.py:825-861 (helper)

Helper function that performs the actual text insertion before the symbol's body start, handling indentation, newlines, and editing context.

def insert_before_symbol_at_location(self, location: SymbolLocation, body: str, *, use_same_indentation: bool = True) -> None:
    """
    Inserts content before the given symbol

    :param location: the location of the symbol before which to add new lines
    :param body: the body of the entity to insert
    """
    with self._edited_symbol_location(location) as symbol:
        symbol_start_pos = symbol.body_start_position
        if symbol_start_pos is None:
            raise ValueError(f"Symbol at {location} does not have a defined start position.")

        if use_same_indentation:
            indent = " " * (symbol_start_pos["character"])
            body = "\n".join(indent + line for line in body.splitlines())

        # insert position is the start of line where the symbol is defined
        line = symbol_start_pos["line"]
        col = 0

        original_trailing_empty_lines = self._count_trailing_newlines(body) - 1

        # ensure eol is present at end
        body = body.rstrip() + "\n"

        # add suitable number of trailing empty lines after the body (at least 0/1 depending on the symbol type,
        # otherwise as many as the caller wanted to insert)
        min_trailing_empty_lines = 0
        if symbol.is_neighbouring_definition_separated_by_empty_line():
            min_trailing_empty_lines = 1
        num_trailing_newlines = max(min_trailing_empty_lines, original_trailing_empty_lines)
        body += "\n" * num_trailing_newlines

        assert location.relative_path is not None

        self._lang_server.insert_text_at_position(location.relative_path, line=line, column=col, text_to_be_inserted=body)

Serena MCP Server