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 | Default |
|---|---|---|---|
| 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)