serena.project

serena.project#

Source code: serena/project.py

class Project(*, project_root, project_config, serena_config, is_newly_created=False)[source]#

Bases: ToStringMixin

Represents a project Serena operates on: the project root and its configuration, file access with gitignore-aware ignore handling, and the connection to the language-server backend that powers the symbolic operations.

Parameters:
save_config()[source]#

Saves the current project configuration to disk.

Return type:

None

is_trusted()[source]#

Checks whether the project is trusted, based on the global configuration.

Returns:

True if the project is trusted, False otherwise

Return type:

bool

read_file(relative_path)[source]#

Reads a project file.

Parameters:

relative_path (str) – the path to the file relative to the project root or an external path token like “<ext:FileUtil.class|472e0a13>”

Returns:

the content of the file

Return type:

str

is_ignored_path(path, ignore_non_source_files=False)[source]#

Checks whether the given path is ignored

Parameters:

  • path (str | Path) – the path to check, can be absolute or relative

  • ignore_non_source_files (bool) – whether to ignore files that are not source files (according to the file masks determined by the project’s programming language)

Return type:

bool

get_is_ignored_path_fn(base_path, skip_ignored_paths)[source]#

Returns a function for checking whether a path should be ignored during a traversal of the given base path.

Parameters:

  • base_path (str) – the relative base path representing the starting point of the traversal. If the path is itself ignored, then the returned function will not consider ignored paths.

  • skip_ignored_paths (bool) – whether to skip ignored (sub-)paths

Returns:

a function that takes a path and returns True if the path should be ignored, False otherwise.

Return type:

Callable[[str], bool]

is_path_in_project(path)[source]#

Checks if the given (absolute or relative) path is inside the project directory.

Note: This is intended to catch cases where “..” segments would lead outside of the project directory, but we intentionally allow symlinks, as the assumption is that they point to relevant project files.

Parameters:

path (str | Path)

Return type:

bool

relative_path_exists(relative_path, require_file=False)[source]#

Checks if the given relative path exists in the project directory.

Parameters:

  • relative_path (str) – the path to check, relative to the project root

  • require_file (bool) – whether to return True only if the path exists and is a file

Returns:

True if the path exists, False otherwise

Return type:

bool

validate_relative_path(relative_path, require_not_ignored=False)[source]#

Validates that the given relative path is within the project directory (and, optionally, not ignored according to the project’s ignore settings), raising a ValueError if the validation fails.

Parameters:

  • relative_path (str) – the path to validate, relative to the project root

  • require_not_ignored (bool) – if True, the path must not be ignored according to the project’s ignore settings

Return type:

None

gather_source_files(relative_path='')[source]#

Retrieves relative paths of all source files, optionally limited to the given path

Parameters:

relative_path (str) – if provided, restrict search to this path

Return type:

list[str]

search_project_files_for_pattern(
pattern,
relative_path='',
context_lines_before=0,
context_lines_after=0,
paths_include_glob=None,
paths_exclude_glob=None,
multiline=True,
code_files_only=True,
skip_ignored_files=True,
)[source]#

Search for a pattern across all (non-ignored) source files

Parameters:

  • pattern (str) – regular expression pattern to search for, either as a compiled Pattern or string

  • relative_path (str) – the relative path to search in, relative to the project root; if empty, search in the entire project

  • context_lines_before (int) – number of lines of context to include before each match

  • context_lines_after (int) – number of lines of context to include after each match

  • paths_include_glob (str | None) – glob pattern to filter which files to include in the search

  • paths_exclude_glob (str | None) – glob pattern to filter which files to exclude from the search. Takes precedence over paths_include_glob.

  • multiline (bool) – whether to compile the regex with the DOTALL flag (. matches newlines).

  • code_files_only (bool) – whether to include only (non-ignored) code files

  • skip_ignored_files (bool) – whether to skip ignored files; has no effect if code_files_only is True

Returns:

list of matches

Return type:

list[MatchedConsecutiveLines]

retrieve_content_around_line(
relative_file_path,
line,
context_lines_before=0,
context_lines_after=0,
)[source]#

Retrieve the content of the given file around the given line.

Parameters:

  • relative_file_path (str) – The relative path of the file to retrieve the content from

  • line (int) – The line number to retrieve the content around

  • context_lines_before (int) – The number of lines to retrieve before the given line

  • context_lines_after (int) – The number of lines to retrieve after the given line

Return MatchedConsecutiveLines:

A container with the desired lines.

Return type:

MatchedConsecutiveLines

create_language_server_manager()[source]#

Creates the language server manager for the project, starting one language server per configured programming language.

Returns:

the language server manager, which is also stored in the project instance

Return type:

LanguageServerManager

get_language_server_manager_status()[source]#
Returns:

a status string describing the state of the language server manager; if its initialisation resulted in an error, the error message is included in the status string

Return type:

str

add_language_server(ls_id)[source]#

Adds a new language server to the project configuration, starting the corresponding server instance if the LS manager is active. The project configuration is saved to disk after adding the language.

Parameters:

ls_id (LanguageServerId) – the language server to add

Return type:

None

remove_language_server(ls_id)[source]#

Removes a language server from the project configuration, stopping the corresponding server instance if the LS manager is active. The project configuration is saved to disk after removing the language.

Parameters:

ls_id (LanguageServerId) – the language server to remove

Return type:

None

ls_sync_file_system_changes()[source]#

Synchronizes file system changes with the project’s associated language server(s), if applicable

Return type:

int