From bf39636a5a48c9ac2cd036343fd6dd413e147349 Mon Sep 17 00:00:00 2001 From: Michael Panchenko Date: Tue, 20 May 2025 16:43:45 +0200 Subject: [PATCH] Docstring --- src/serena/agent.py | 16 +++++++++++++++- src/serena/symbol.py | 29 +++++++---------------------- 2 files changed, 22 insertions(+), 23 deletions(-) diff --git a/src/serena/agent.py b/src/serena/agent.py index 0c8d5d1..a60b09d 100644 --- a/src/serena/agent.py +++ b/src/serena/agent.py @@ -794,8 +794,22 @@ class FindSymbolTool(Tool): or to retrieve further information using other tools. If you already anticipate that you will need to reference children of the symbol (like methods or fields contained in a class), you can specify a depth > 0. + + The name matching behavior depends on whether a qualified name or a simple name is provided. + It is assumed that the provided name is a qualified name if it contains the `/` character. + If substring matching is allowed, only the last element of the qualified name will be checked against + the symbol name using substring matching. - :param name: the name of the symbols to find + Examples: + - Providing "foo" will find all symbols named "foo" regardless where they are contained in the symbol tree. + - Providing "bar/foo" will only find symbols named "foo" that are direct children of a symbol called "bar". + - Providing "foo/" will only find symbols named "foo" that are top-level symbols (have no parent). + - Allowing substring matching with "bar" will find symbols with names containing "foo" anywhere in the symbol tree. + - Allowing substring matching with "foo/" will find only top-level symbols with names containing "foo". + - Allowing substring matching with "bar/foo" will find only symbols with names containing "foo" that are direct children of a symbol named "bar". + + :param name: the name of the symbols to find. A "qualified" name that includes the symbol's parents + separated by `/` (e.g. "class/method/inner_function") can be used to restrict the search. :param depth: specifies the depth up to which descendants of the symbol are to be retrieved (e.g. depth 1 will retrieve methods and attributes for the case where the symbol refers to a class). Provide a non-zero depth if you intend to subsequently query symbols that are contained in the diff --git a/src/serena/symbol.py b/src/serena/symbol.py index 1ccbb76..7a6e227 100644 --- a/src/serena/symbol.py +++ b/src/serena/symbol.py @@ -233,7 +233,6 @@ class Symbol(ToStringMixin): If substring matching is allowed, only the last element of the qualified name will be checked against the symbol name using substring matching. - Examples: - Providing "foo" will find all symbols named "foo" regardless where they are contained in the symbol tree. - Providing "bar/foo" will only find symbols named "foo" that are direct children of a symbol called "bar". @@ -242,8 +241,8 @@ class Symbol(ToStringMixin): - Allowing substring matching with "foo/" will find only top-level symbols with names containing "foo". - Allowing substring matching with "bar/foo" will find only symbols with names containing "foo" that are direct children of a symbol named "bar". - :param name: the name of the symbol to find. Can use a qualified name (e.g. "class/method/inner_function") - to restrict the search. + :param name: the name of the symbols to find. A "qualified" name that includes the symbol's parents + separated by `/` (e.g. "class/method/inner_function") can be used to restrict the search. :param substring_matching: whether to use substring matching for the symbol name. If a qualified name is provided, the last element of the qualified name will be checked against the symbol name using substring matching. @@ -290,7 +289,7 @@ class Symbol(ToStringMixin): and pass the children without passing the parent body to the LM. :return: a dictionary representation of the symbol """ - result: dict[str, Any] = {"name": self.name} + result: dict[str, Any] = {"name": self.name, "qualname": self.get_qualified_name()} if kind: result["kind"] = self.kind @@ -334,30 +333,16 @@ class SymbolManager: def find_by_name( self, name: str, - within_relative_path: str | None = None, include_body: bool = False, include_kinds: Sequence[SymbolKind] | None = None, exclude_kinds: Sequence[SymbolKind] | None = None, substring_matching: bool = False, + within_relative_path: str | None = None, ) -> list[Symbol]: """ - Find all symbols that match the given name. - - :param name: the name of the symbol to find - :param within_relative_path: pass a relative path to only consider symbols within this path. - If a file is passed, only the symbols within this file will be considered. - If a directory is passed, all files within this directory will be considered. - If None, the entire codebase will be considered. - :param include_body: whether to include the body of all symbols in the result. - 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. - :param substring_matching: whether to use substring matching for the symbol name. - If True, the symbol name will be matched if it contains the given name as a substring. - :return: a list of symbols that match the given name + Find all symbols that match the given name. See docstring of `Symbol.find` for more details. + The only parameter not mentioned there is `within_relative_path`, which can be used to restrict the search + to symbols within a specific file or directory. """ symbols: list[Symbol] = [] symbol_roots = self.lang_server.request_full_symbol_tree(within_relative_path=within_relative_path, include_body=include_body)