find_referencing_symbols
Locate symbols that reference a specific symbol in your codebase, including subclasses and usage points, to analyze dependencies and inheritance.
Instructions
Finds symbols that reference 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 (unless include_body is True, then the short snippet will be omitted).
Note that among other kinds of references, this function can be used to find (direct) subclasses of a class,
as subclasses are referencing symbols that have the kind class. Returns a list of JSON objects with the symbols referencing the requested symbol.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name_path | Yes | For finding the symbol to find references for, same logic as in the `find_symbol` tool. | |
| relative_path | Yes | The relative path to the file containing the symbol for which to find references. Note that here you can't pass a directory but must pass a file. | |
| include_kinds | No | Same as in the `find_symbol` tool. | |
| exclude_kinds | No | Same as in the `find_symbol` tool. | |
| max_answer_chars | No | Same as in the `find_symbol` tool. |
Implementation Reference
- src/serena/symbol.py:553-632 (handler)Core handler logic for the find_referencing_symbols tool. Finds referencing symbols by first locating the symbol by name and file, then using LSP to find references at its location. Filters by kinds if specified.def find_referencing_symbols( self, name_path: str, relative_file_path: str, include_body: bool = False, include_kinds: Sequence[SymbolKind] | None = None, exclude_kinds: Sequence[SymbolKind] | None = None, ) -> list[ReferenceInSymbol]: """ Find all symbols that reference the symbol with the given name. If multiple symbols fit the name (e.g. for variables that are overwritten), will use the first one. :param name_path: the name path of the symbol to find :param relative_file_path: the relative path of the file in which the referenced symbol is defined. :param include_body: whether to include the body of all symbols in the result. Not recommended, as the referencing symbols will often be files, and thus the bodies will be very long. :param include_kinds: which kinds of symbols to include in the result. :param exclude_kinds: which kinds of symbols to exclude from the result. """ symbol_candidates = self.find_by_name(name_path, substring_matching=False, within_relative_path=relative_file_path) if len(symbol_candidates) == 0: log.warning(f"No symbol with name {name_path} found in file {relative_file_path}") return [] if len(symbol_candidates) > 1: log.error( f"Found {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 for {name_path=} in {relative_file_path=}: \n" f"{json.dumps([s.location.to_dict() for s in symbol_candidates], indent=2)}" ) symbol = symbol_candidates[0] return self.find_referencing_symbols_by_location( symbol.location, include_body=include_body, include_kinds=include_kinds, exclude_kinds=exclude_kinds ) def find_referencing_symbols_by_location( self, symbol_location: SymbolLocation, include_body: bool = False, include_kinds: Sequence[SymbolKind] | None = None, exclude_kinds: Sequence[SymbolKind] | None = None, ) -> list[ReferenceInSymbol]: """ Find all symbols that reference the symbol at the given location. :param symbol_location: the location of the symbol for which to find references. Does not need to include an end_line, as it is unused in the search. :param include_body: whether to include the body of all symbols in the result. Not recommended, as the referencing symbols will often be files, and thus the bodies will be very long. Note: you can filter out the bodies of the children if you set include_children_body=False in the to_dict method. :param include_kinds: an optional sequence of ints representing the LSP symbol kind. If provided, only symbols of the given kinds will be included in the result. :param exclude_kinds: If provided, symbols of the given kinds will be excluded from the result. Takes precedence over include_kinds. :return: a list of symbols that reference the given symbol """ if not symbol_location.has_position_in_file(): raise ValueError("Symbol location does not contain a valid position in a file") assert symbol_location.relative_path is not None assert symbol_location.line is not None assert symbol_location.column is not None references = self._lang_server.request_referencing_symbols( relative_file_path=symbol_location.relative_path, line=symbol_location.line, column=symbol_location.column, include_imports=False, include_self=False, include_body=include_body, include_file_symbols=True, ) if include_kinds is not None: references = [s for s in references if s.symbol["kind"] in include_kinds] if exclude_kinds is not None: references = [s for s in references if s.symbol["kind"] not in exclude_kinds] return [ReferenceInSymbol.from_lsp_reference(r) for r in references]
- src/serena/symbol.py:479-496 (helper)Dataclass representing a reference to a symbol, used in the return type of the handler.@dataclass class ReferenceInSymbol(ToStringMixin): """Same as the class of the same name in the language server, but using Serena's Symbol class. Be careful to not confuse it with counterpart! """ symbol: Symbol line: int character: int def get_relative_path(self) -> str | None: return self.symbol.location.relative_path @classmethod def from_lsp_reference(cls, reference: LSPReferenceInSymbol) -> Self: return cls(symbol=Symbol(reference.symbol), line=reference.line, character=reference.character)