serena.jetbrains.jetbrains_plugin_client

serena.jetbrains.jetbrains_plugin_client#

Source code: serena/jetbrains/jetbrains_plugin_client.py

Client for the Serena JetBrains Plugin

exception SerenaClientError[source]#

Bases: Exception

Base exception for Serena client errors.

exception ConnectionError[source]#

Bases: SerenaClientError

Raised when connection to the service fails.

exception APIError(response)[source]#

Bases: SerenaClientError

Raised when the API returns an error response that shall be reported on the caller/LLM.

Parameters:

response (Response)

exception PluginServerError(message)[source]#

Bases: SerenaClientError

Raised when the plugin’s service encounters an internal error (which may need to be reported).

Parameters:

message (str)

exception ServerNotFoundError[source]#

Bases: Exception

Raised when the plugin’s service is not found.

class MatchedClient(
client: 'JetBrainsPluginClient',
registered_project: RegisteredProject,
)[source]#

Bases: object

Parameters:
class JetBrainsPluginClient(port, timeout=300)[source]#

Bases: ToStringMixin

Python client for the Serena Backend Service.

Provides simple methods to interact with all available endpoints.

Parameters:

  • port (int)

  • timeout (int)

PLUGIN_REQUEST_TIMEOUT = 300#

the timeout used for request handling within the plugin (a constant in the plugin)

matches(resolved_path)[source]#
Parameters:

resolved_path (Path) – the resolved project root path from Serena’s perspective

Returns:

whether this client instance matches the given project path

Return type:

bool

find_symbol(
name_path,
relative_path=None,
include_body=False,
include_quick_info=False,
include_documentation=False,
include_num_usages=False,
depth=0,
include_location=False,
search_deps=False,
)[source]#

Finds symbols by name.

Parameters:

  • name_path (str) – the name path to match

  • relative_path (str | None) – the relative path to which to restrict the search

  • include_body (bool) – whether to include symbol body content (should typically not be combined with include_quick_info or include_documentation because the body includes everything)

  • include_quick_info (bool) – whether to include quick info (typically the signature)

  • include_documentation (bool) – whether to include documentation; note that this includes the quick info, so one should not pass both include_quick_info and this

  • include_num_usages (bool) – whether to include the number of usages

  • depth (int) – depth up to which to include children (0 = no children)

  • include_location (bool) – whether to include symbol location information

  • search_deps (bool) – whether to also search in dependencies

Return type:

SymbolCollectionResponse

find_references(name_path, relative_path, include_quick_info)[source]#

Finds references to a symbol.

Parameters:

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

  • relative_path (str) – the relative path

  • include_quick_info (bool) – whether to include quick info about references

Return type:

SymbolCollectionResponse

get_symbols_overview(
relative_path,
depth,
include_file_documentation=False,
)[source]#
Parameters:

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

  • depth (int) – the depth of children to include (0 = no children)

  • include_file_documentation (bool) – whether to include the file’s documentation string (if any)

Return type:

GetSymbolsOverviewResponse

get_supertypes(
name_path,
relative_path,
depth=None,
limit_children=None,
)[source]#

Gets the supertypes (parent classes/interfaces) of a symbol.

Parameters:

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

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

  • depth (int | None) – depth limit for hierarchy traversal (None or 0 for unlimited)

  • limit_children (int | None) – optional limit on children per level

Return type:

TypeHierarchyResponse

get_subtypes(
name_path,
relative_path,
depth=None,
limit_children=None,
)[source]#

Gets the subtypes (subclasses/implementations) of a symbol.

Parameters:

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

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

  • depth (int | None) – depth limit for hierarchy traversal (None or 0 for unlimited)

  • limit_children (int | None) – optional limit on children per level

Return type:

TypeHierarchyResponse

safe_delete(
name_path,
relative_path,
delete_even_if_used,
propagate,
)[source]#

Safely deletes a symbol, checking for usages first.

Parameters:

  • name_path (str | None) – the name path of the symbol to delete

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

  • delete_even_if_used (bool) – if True, delete the symbol even if it has usages

  • propagate (bool)

Return type:

dict[str, Any]

inline_symbol(name_path, relative_path, keep_definition)[source]#

Inlines a method, replacing all call sites with the method body.

Parameters:

  • name_path (str) – the name path of the method to inline

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

  • keep_definition (bool) – if True, keep the original method definition after inlining

Return type:

dict[str, Any]

rename_symbol(
name_path,
relative_path,
new_name,
rename_in_comments,
rename_in_text_occurrences,
)[source]#

Renames a symbol.

Parameters:

  • name_path (str | None) – the name path of the symbol

  • relative_path (str) – the relative path

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

  • rename_in_comments (bool) – whether to rename in comments

  • rename_in_text_occurrences (bool) – whether to rename in text occurrences

Return type:

None

refresh_file(relative_path)[source]#

Triggers a refresh of the given file in the IDE.

Parameters:

relative_path (str) – the relative path

Return type:

None

find_declaration(
relative_path,
line,
col,
include_body,
include_quick_info,
)[source]#

Finds the declaration of the symbol at the given location.

Parameters:

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

  • line (int) – the line number (0-based)

  • col (int) – the column number (0-based)

  • include_body (bool) – whether to include the symbol body

  • include_quick_info (bool) – whether to include quick info about the symbol

Return type:

SymbolCollectionResponse

find_implementations(relative_path, name_path, include_quick_info)[source]#

Finds the implementations of a symbol.

Parameters:

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

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

  • include_quick_info (bool) – whether to include quick info about the symbol

Return type:

SymbolCollectionResponse

debug_eval(repl_key, expression)[source]#

Evaluates a Groovy expression in the persistent debug REPL.

Parameters:

  • repl_key (str) – the session key identifying the REPL instance

  • expression (str) – the Groovy expression to evaluate

Returns:

the response containing REPL key and result

Return type:

dict[str, Any]

debug_close(repl_key)[source]#

Closes the debug REPL for the given session key, clearing all state.

Parameters:

repl_key (str) – the key identifying the REPL instance to close

Returns:

the status response

Return type:

dict[str, Any]

run_inspections(
relative_path,
min_severity=None,
inspection_names=None,
start_line=None,
end_line=None,
)[source]#

Runs IDE inspections on the given file and returns the results.

Parameters:

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

  • min_severity (str | None) – minimum severity level to include (e.g. “WARNING”, “ERROR”)

  • inspection_names (list[str] | None) – optional list of specific inspection names to run

  • start_line (int | None) – optional start line to restrict the inspection range

  • end_line (int | None) – optional end line to restrict the inspection range

Returns:

the inspection results as a dictionary. NOTE: The response is currently not a well-defined DTO, because it stores variable data in keys. Consequently, the pythonify option is disabled for this request, and the response is returned as-is.

Return type:

dict

list_inspections(language=None, group_path_contains=None)[source]#

Lists available IDE inspections, optionally filtered by language and/or group path.

Parameters:

  • language (str | None) – optional language to filter inspections by (e.g. “Java”, “Python”)

  • group_path_contains (str | None) – optional substring to filter inspection group paths

Return type:

ListInspectionsResponse