serena.tools.symbol_tools

serena.tools.symbol_tools#

Source code: serena/tools/symbol_tools.py

Language server-related tools

class RestartLanguageServerTool(agent)[source]#

Bases: Tool, ToolMarkerOptional

Restarts the language server(s).

Parameters:

agent (SerenaAgent)

apply()[source]#

Use this tool only on explicit user request or after confirmation. It may be necessary to restart the language server if it hangs.

Return type:

str

class GetSymbolsOverviewTool(agent)[source]#

Bases: Tool, ToolMarkerSymbolicRead

Gets an overview of the top-level symbols defined in a given file.

Parameters:

agent (SerenaAgent)

apply(relative_path, depth=-1, max_answer_chars=-1)[source]#

Use this tool to get a high-level understanding of the code symbols in a file. This should be the first tool to call when you want to understand a new file, unless you already know what you are looking for.

Parameters:

  • relative_path (str) – the relative path to the file to get the overview of

  • depth (int) – depth up to which descendants shall be retrieved. Default (-1) results in a language specific choice: 1 for java and kotlin and 0 for other languages

  • max_answer_chars (int) – if the overview is longer than this number of characters, no content will be returned. -1 means the default value from the config will be used. Don’t adjust unless there is really no other way to get the content required for the task.

Returns:

a JSON object containing symbols grouped by kind in a compact format.

Return type:

str

get_symbol_overview(relative_path, depth=0)[source]#
Parameters:

  • relative_path (str) – relative path to a source file

  • depth (int) – the depth up to which descendants shall be retrieved

Returns:

a list of symbol dictionaries representing the symbol overview of the file

Return type:

list[OutputDict]

class FindSymbolTool(agent)[source]#

Bases: Tool, ToolMarkerSymbolicRead

Performs a global (or local) search using the language server backend.

Parameters:

agent (SerenaAgent)

apply(
name_path_pattern,
depth=0,
relative_path='',
include_body=False,
include_info=False,
include_kinds=[],
exclude_kinds=[],
substring_matching=False,
max_matches=-1,
max_answer_chars=-1,
)[source]#

Finds symbols and code entities (classes, methods, etc.) based on the given name path pattern. The returned symbol information can be used for edits or further queries. Specify depth > 0 to also retrieve children/descendants (e.g., methods of a class).

A name path is a path in the symbol tree within a source file. For example, the method my_method defined in class MyClass would have the name path MyClass/my_method. If a symbol is overloaded (e.g., in Java), a 0-based index is appended (e.g. “MyClass/my_method[0]”) to uniquely identify it.

To search for a symbol, you provide a name path pattern that is used to match against name paths. It can be

  • a simple name (e.g. “method”), which will match any symbol with that name

  • a relative path like “class/method”, which will match any symbol with that name path suffix

  • an absolute name path “/class/method” (absolute name path), which requires an exact match of the full name path within the source file.

Append an index [i] to match a specific overload only, e.g. “MyClass/my_method[1]”.

Parameters:

  • name_path_pattern (str) – the name path matching pattern (see above)

  • depth (int) – depth up to which descendants shall be retrieved (e.g. use 1 to also retrieve immediate children; for the case where the symbol is a class, this will return its methods). Ignored if include_body=True. Default 0.

  • relative_path (str) – (optional) restrict search to this file or directory. If None, searches entire codebase. If a directory is passed, the search will be restricted to the files in that directory. If a file is passed, the search will be restricted to that file.

  • include_body (bool) – whether to include the symbol’s source code. Use judiciously.

  • include_info (bool) – whether to include additional info (hover-like, typically including docstring and signature), about the symbol (ignored if include_body is True). Info is never included for child symbols. Note: Depending on the language, this can be slow (e.g., C/C++).

  • include_kinds (list[int]) – (optional) limits results to the given LSP symbol kinds (integers)

  • exclude_kinds (list[int]) – (optional) list of LSP symbol kinds (integers) to exclude.

  • substring_matching (bool) – If True, use substring matching for the last element of the pattern, such that “Foo/get” would match “Foo/getValue” and “Foo/getData”.

  • max_matches (int) – maximum number of permitted matches. If exceeded, a shortened result is returned which allows refining the search. -1 (default) means no limit. Set to 1 if you search for a single symbol.

  • max_answer_chars (int) – max result length; -1 for default

Returns:

symbols (with locations) matching the name.

Return type:

str

classmethod get_param_aliases()[source]#
Returns:

a mapping of parameter aliases for the apply method, where the key is the alias and the value is the actual parameter name. This can be used to define alternative parameter names for the same parameter.

Return type:

dict[str, str]

class FindReferencingSymbolsTool(agent)[source]#

Bases: Tool, ToolMarkerSymbolicRead

Finds symbols that reference the given symbol using the language server backend

Parameters:

agent (SerenaAgent)

apply(
name_path,
relative_path,
include_kinds=[],
exclude_kinds=[],
max_answer_chars=-1,
)[source]#

Finds references to the symbol at the given name_path. The result will contain metadata about the referencing symbols as well as a short code snippet around the reference.

Parameters:

  • name_path (str) – name path of the symbol

  • relative_path (str) – the relative path to the file containing the symbol for which to find references.

  • include_kinds (list[int]) – (optional) limits results to the given LSP symbol kinds (integers)

  • exclude_kinds (list[int]) – optional list of LSP symbol kinds (integers) to exclude.

  • max_answer_chars (int) – max result length; -1 for default

Returns:

a list of JSON objects with the symbols referencing the requested symbol

Return type:

str

class FindImplementationsTool(agent)[source]#

Bases: Tool, ToolMarkerSymbolicRead

Finds symbols that implement the given symbol using the language server backend.

Parameters:

agent (SerenaAgent)

apply(
name_path,
relative_path,
include_info=False,
include_kinds=[],
exclude_kinds=[],
max_answer_chars=-1,
)[source]#

Finds implementations of the symbol at the given name_path.

Parameters:

  • name_path (str) – the symbol’s name path

  • relative_path (str) – the relative path to the file containing the symbol for which to find implementations. Note that here you can’t pass a directory but must pass a file.

  • include_info (bool) – whether to include additional info (hover-like, typically including docstring and signature), about the implementing symbols.

  • include_kinds (list[int]) – (optional) limits results to the given LSP symbol kinds (integers)

  • exclude_kinds (list[int]) – (optional) list of LSP symbol kinds (integers) to exclude.

  • max_answer_chars (int) – max result length; -1 for default

Returns:

a list of JSON objects with the symbols implementing the requested symbol

Return type:

str

class FindDeclarationTool(agent)[source]#

Bases: Tool, ToolMarkerSymbolicRead

Finds the declaration/definition of a symbol

Parameters:

agent (SerenaAgent)

apply(
relative_path,
regex,
containing_symbol_name_path=None,
include_body=False,
include_info=False,
)[source]#

Finds the declaration of a symbol.

Parameters:

  • relative_path (str) – the relative path to the source file containing the symbol for which to find the declaration.

  • regex (str) – a regular expression with one group, where the group matches the symbol for which to perform the lookup. For example, to find the declaration of the process method in a call like obj.process(), pass an expression like “obj.(process)(process_input_arg=37)”. Prefer regexes with sufficiently large context around the group to render the match unambiguous. Uses Python syntax with MULTILINE and DOTALL flags enabled.

  • containing_symbol_name_path (str | None) – optional name path of a containing symbol whose body shall be searched instead of the full file.

  • include_body (bool) – whether to include the symbol’s body in the result. Default False.

  • include_info (bool) – whether to include additional info (hover-like). Default False.

Return type:

str

class GetDiagnosticsForFileTool(agent)[source]#

Bases: Tool, ToolMarkerSymbolicRead

Gets diagnostics for a file, optionally restricted to a line range, grouped by file, severity, and containing symbol.

Parameters:

agent (SerenaAgent)

apply(
relative_path,
start_line=0,
end_line=-1,
min_severity=4,
max_answer_chars=-1,
)[source]#

Gets diagnostics for a file. Diagnostics are grouped as relative_path -> severity -> name_path -> diagnostics_results. If a diagnostic cannot be mapped to a symbol, it is grouped under the special name path <file>.

Parameters:

  • relative_path (str) – the relative path to the file to inspect.

  • start_line (int) – the first 0-based line to include. Defaults to 0.

  • end_line (int) – the last 0-based line to include. Defaults to -1, which means until the end of the file.

  • min_severity (int) – minimum LSP severity to include, where 1=Error, 2=Warning, 3=Information, 4=Hint. Diagnostics with lower-or-equal numeric severity are returned.

  • max_answer_chars (int) – max result length; -1 for default

Returns:

grouped diagnostics for the requested file.

Return type:

str

class GetDiagnosticsForSymbolTool(agent)[source]#

Bases: Tool, ToolMarkerSymbolicRead, ToolMarkerOptional

Gets diagnostics for a symbol and, optionally, for symbols that reference it.

Parameters:

agent (SerenaAgent)

apply(
name_path,
reference_file='',
check_symbol_references=False,
min_severity=4,
max_answer_chars=-1,
)[source]#

Gets diagnostics for the specified symbol. When check_symbol_references is true, diagnostics for all referencing symbols are also included. The result is grouped as relative_path -> severity -> name_path -> diagnostics_results.

Parameters:

  • name_path (str) – the name path of the symbol to inspect.

  • reference_file (str) – optional file path used to disambiguate the symbol search.

  • check_symbol_references (bool) – whether to additionally collect diagnostics for symbols that reference the symbol.

  • min_severity (int) – minimum LSP severity to include, where 1=Error, 2=Warning, 3=Information, 4=Hint. Diagnostics with lower-or-equal numeric severity are returned.

  • max_answer_chars (int) – max result length; -1 for default

Returns:

grouped diagnostics for the requested symbol and, optionally, its referencing symbols.

Return type:

str

class ReplaceSymbolBodyTool(agent)[source]#

Bases: EditingToolWithDiagnostics

Replaces the full definition of a symbol using the language server backend.

Parameters:

agent (SerenaAgent)

apply(name_path, relative_path, body)[source]#

Replaces the body of the given symbol.

IMPORTANT: Only replace symbol bodies if you have previously made a retrieval with include_body=True and thus know what constitutes the body!

Parameters:

  • name_path (str) – name path of the symbol whose body to replace

  • relative_path (str) – the relative path to the file containing the symbol

  • body (str) – the new symbol body. The symbol body is the definition of a symbol in the programming language, including e.g. the signature line for functions. Depending on the language, it may or may not include a preceding docstring or other preceding annotations.

Return type:

str

class InsertAfterSymbolTool(agent)[source]#

Bases: EditingToolWithDiagnostics

Inserts content after the end of the definition of a given symbol.

Parameters:

agent (SerenaAgent)

apply(name_path, relative_path, body)[source]#

Use this to insert code after a class/method/function definition. Don’t use to insert after assignments (constants, fields).

Parameters:

  • name_path (str) – name path of the symbol after which to insert content

  • relative_path (str) – the relative path to the file containing the symbol

  • body (str) – the body/content to be inserted. The inserted code shall begin with the next line after the symbol.

Return type:

str

class InsertBeforeSymbolTool(agent)[source]#

Bases: EditingToolWithDiagnostics

Inserts content before the beginning of the definition of a given symbol.

Parameters:

agent (SerenaAgent)

apply(name_path, relative_path, body)[source]#

Inserts the given 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; or a new import statement before the first symbol in the file.

Parameters:

  • name_path (str) – name path of the symbol before which to insert content

  • relative_path (str) – the relative path to the file containing the symbol

  • body (str) – the body/content to be inserted before the line in which the referenced symbol is defined

Return type:

str

class RenameSymbolTool(agent)[source]#

Bases: Tool, ToolMarkerSymbolicEdit

Renames a symbol throughout the codebase using language server refactoring capabilities. For JB, we use a separate tool.

Parameters:

agent (SerenaAgent)

apply(name_path, relative_path, new_name)[source]#

Renames the symbol with the given name_path to new_name throughout the entire codebase. Note: for languages with method overloading, like Java, name_path may have to include a method’s signature to uniquely identify a method.

Parameters:

  • name_path (str) – name path of the symbol to rename

  • relative_path (str) – the relative path to the file containing the symbol to rename

  • new_name (str) – the new name for the symbol

Returns:

result summary indicating success or failure

Return type:

str

class SafeDeleteSymbol(agent)[source]#

Bases: Tool, ToolMarkerSymbolicEdit

Parameters:

agent (SerenaAgent)

apply(name_path_pattern, relative_path)[source]#

Deletes the symbol if it is safe to do so (i.e., if there are no references to it) or returns a list of references to it.

Parameters:

  • name_path_pattern (str) – name path of the symbol to delete

  • relative_path (str) – the relative path to the file containing the symbol to delete

Return type:

str