serena.symbol

serena.symbol#

Source code: serena/symbol.py

class LanguageServerSymbolLocation(relative_path, line, column)[source]#

Bases: object

Represents the (start) location of a symbol identifier, which, within Serena, uniquely identifies the symbol.

Parameters:

  • relative_path (str | None)

  • line (int | None)

  • column (int | None)

relative_path: str | None#

the relative path of the file containing the symbol; if None, the symbol is defined outside of the project’s scope

line: int | None#

the line number in which the symbol identifier is defined (if the symbol is a function, class, etc.); may be None for some types of symbols (e.g. SymbolKind.File)

column: int | None#

the column number in which the symbol identifier is defined (if the symbol is a function, class, etc.); may be None for some types of symbols (e.g. SymbolKind.File)

class PositionInFile(line, col)[source]#

Bases: object

Represents a character position within a file

Parameters:

  • line (int)

  • col (int)

line: int#

the 0-based line number in the file

col: int#

the 0-based column

to_lsp_position()[source]#

Convert to LSP Position.

Return type:

Position

class Symbol[source]#

Bases: ToStringMixin, ABC

get_body_start_position_or_raise()[source]#

Get the start position of the symbol body, raising an error if it is not defined.

Return type:

PositionInFile

get_body_end_position_or_raise()[source]#

Get the end position of the symbol body, raising an error if it is not defined.

Return type:

PositionInFile

abstract is_neighbouring_definition_separated_by_empty_line()[source]#
Returns:

whether a symbol definition of this symbol’s kind is usually separated from the previous/next definition by at least one empty line.

Return type:

bool

class NamePathMatcher(name_path_pattern, substring_matching)[source]#

Bases: ToStringMixin

Matches name paths of symbols against search patterns.

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.

A matching pattern 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 expression to match against

  • substring_matching (bool) – whether to use substring matching for the last segment

class LanguageServerSymbol(symbol_root_from_ls)[source]#

Bases: Symbol, ToStringMixin

Parameters:

symbol_root_from_ls (UnifiedSymbolInformation)

property symbol_kind_name: str#
Returns:

string representation of the symbol kind (name attribute of the SymbolKind enum item)

is_low_level()[source]#
Returns:

whether the symbol is a low-level symbol (variable, constant, etc.), which typically represents data rather than structure and therefore is not relevant in a high-level overview of the code.

Return type:

bool

is_neighbouring_definition_separated_by_empty_line()[source]#
Returns:

whether a symbol definition of this symbol’s kind is usually separated from the previous/next definition by at least one empty line.

Return type:

bool

property location: LanguageServerSymbolLocation#
Returns:

the start location of the actual symbol identifier

property line: int | None#
Returns:

the line in which the symbol identifier is defined.

get_name_path()[source]#

Get the name path of the symbol, e.g. “class/method/inner_function” or “class/method[1]” (overloaded method with identifying index).

Return type:

str

iter_ancestors(up_to_symbol_kind=None)[source]#

Iterate over all ancestors of the symbol, starting with the parent and going up to the root or the given symbol kind.

Parameters:

up_to_symbol_kind (SymbolKind | None) – if provided, iteration will stop before the first ancestor of the given kind. A typical use case is to pass SymbolKind.File or SymbolKind.Package.

Return type:

Iterator[Self]

find(
name_path_pattern,
substring_matching=False,
include_kinds=None,
exclude_kinds=None,
)[source]#

Find all symbols within the symbol’s subtree that match the given name path pattern.

Parameters:

  • name_path_pattern (str) – the name path pattern to match against (see class NamePathMatcher for details)

  • substring_matching (bool) – whether to use substring matching (as opposed to exact matching) of the last segment of name_path against the symbol name.

  • include_kinds (Sequence[SymbolKind] | None) – an optional sequence of ints representing the LSP symbol kind. If provided, only symbols of the given kinds will be included in the result.

  • exclude_kinds (Sequence[SymbolKind] | None) – If provided, symbols of the given kinds will be excluded from the result.

Return type:

list[Self]

class OutputDict[source]#

Bases: TypedDict

kind: NotRequired[str]#

string representation of the symbol kind (name attribute of the SymbolKind enum item)

content_around_reference: NotRequired[str]#

set by FindReferencingSymbolsTool when including surrounding code lines

reference_line: NotRequired[int]#

line number of the reference, set by FindReferencingSymbolsTool

to_dict(
*,
name_path=True,
name=False,
kind=False,
location=False,
depth=0,
body=False,
body_location=False,
children_body=False,
children_name_path=None,
children_name=None,
relative_path=False,
child_inclusion_predicate=None,
)[source]#

Converts the symbol to a dictionary.

Parameters:

  • name_path (bool) – whether to include the name path of the symbol

  • name (bool) – whether to include the name of the symbol

  • kind (bool) – whether to include the kind of the symbol

  • location (bool) – whether to include the location of the symbol

  • depth (int) – the depth up to which to include child symbols (0 = do not include children)

  • body (bool) – whether to include the body of the top-level symbol.

  • children_body (bool) – whether to also include the body of the children. Note that the body of the children is part of the body of the parent symbol, so there is usually no need to set this to True unless you want process the output and pass the children without passing the parent body to the LM.

  • children_name_path (bool | None) – whether to include the name path of the children; if None, defaults to the value of name_path

  • children_name (bool | None) – whether to include the name of the children; if None, defaults to the value of name

  • relative_path (bool) – whether to include the relative path of the symbol. If location is True, this defines whether to include the path in the location entry. If location is False, this defines whether to include the relative path as a top-level entry. Relative paths of the symbol’s children are always excluded.

  • child_inclusion_predicate (Callable[[Self], bool] | None) – an optional predicate that decides whether a child symbol should be included.

  • body_location (bool)

Returns:

a dictionary representation of the symbol

Return type:

OutputDict

class ReferenceInLanguageServerSymbol(symbol, line, character)[source]#

Bases: ToStringMixin

Represents the location of a reference to another symbol within a symbol/file.

The contained symbol is the symbol within which the reference is located, not the symbol that is referenced.

Parameters:
symbol: LanguageServerSymbol#

the symbol within which the reference is located

line: int#

the line number in which the reference is located (0-based)

character: int#

the column number in which the reference is located (0-based)

class JetBrainsSymbol(symbol_dict, project)[source]#

Bases: Symbol

Parameters:

  • symbol_dict (SymbolDTO) – dictionary as returned by the JetBrains plugin client.

  • project (Project)

is_neighbouring_definition_separated_by_empty_line()[source]#
Returns:

whether a symbol definition of this symbol’s kind is usually separated from the previous/next definition by at least one empty line.

Return type:

bool

class SymbolDictGrouper(
symbol_dict_type,
children_key,
group_keys,
group_children_keys,
collapse_singleton,
)[source]#

Bases: Generic[TSymbolDict], ABC

A utility class for grouping a list of symbol dictionaries by one or more specified keys.

If an instance is statically initialised (upon module import), then this establishes a guarantee that the specified keys are defined in the symbol dictionary type, ensuring at least basic type safety. The respective ValueError will immediately be apparent.

Parameters:

  • symbol_dict_type (type[TSymbolDict]) – the TypedDict type that represents the type of the symbol dictionaries to be grouped

  • children_key (Any) – the key in the symbol dictionaries that contains the list of child symbols (for recursive grouping).

  • group_keys (list[Any]) – keys by which to group the symbol dictionaries. Must be a subset of the keys of symbol_dict_type.

  • group_children_keys (list[Any]) – keys by which to group the child symbol dictionaries. Must be a subset of the keys of symbol_dict_type.

  • collapse_singleton (bool) – whether to collapse dictionaries containing a single entry after regrouping to just the entry’s value

group(symbols)[source]#
Parameters:

symbols (list[TSymbolDict]) – the symbols to group

Returns:

dictionary with the symbols grouped as defined at construction if at least one key was used for grouping, otherwise the list of symbols (potentially transformed)

Return type:

dict[str, list[dict] | dict[str, dict]] | list

disabled_context()[source]#

A context manager that temporarily disables grouping.

Return type:

Iterator[None]

class LanguageServerSymbolDictGrouper(
group_keys,
group_children_keys,
collapse_singleton=False,
)[source]#

Bases: SymbolDictGrouper[OutputDict]

Parameters:

  • symbol_dict_type – the TypedDict type that represents the type of the symbol dictionaries to be grouped

  • children_key – the key in the symbol dictionaries that contains the list of child symbols (for recursive grouping).

  • group_keys (list[Literal['name', 'name_path', 'relative_path', 'location', 'body_location', 'body', 'kind', 'children', 'content_around_reference', 'reference_line']]) – keys by which to group the symbol dictionaries. Must be a subset of the keys of symbol_dict_type.

  • group_children_keys (list[Literal['name', 'name_path', 'relative_path', 'location', 'body_location', 'body', 'kind', 'children', 'content_around_reference', 'reference_line']]) – keys by which to group the child symbol dictionaries. Must be a subset of the keys of symbol_dict_type.

  • collapse_singleton (bool) – whether to collapse dictionaries containing a single entry after regrouping to just the entry’s value

class JetBrainsSymbolDictGrouper(
group_keys,
group_children_keys,
collapse_singleton=False,
map_name_path_to_name=False,
)[source]#

Bases: SymbolDictGrouper[SymbolDTO]

Parameters:

  • group_keys (list[Literal['name_path', 'relative_path', 'type', 'body', 'quick_info', 'documentation', 'text_range', 'children', 'num_usages', 'reference_line_no', 'context']]) – keys to group main symbols by

  • group_children_keys (list[Literal['name_path', 'relative_path', 'type', 'body', 'quick_info', 'documentation', 'text_range', 'children', 'num_usages', 'reference_line_no', 'context']]) – keys to group child symbols by

  • collapse_singleton (bool) – whether to collapse singleton symbol dictionaries

  • map_name_path_to_name (bool) – whether to transform the “name_path” key of child symbols to the bare “name”