serena.util.text_utils

serena.util.text_utils#

Source code: serena/util/text_utils.py

class LineType(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)[source]#

Bases: StrEnum

Enum for different types of lines in search results.

MATCH = 'match'#

Part of the matched lines

BEFORE_MATCH = 'prefix'#

Lines before the match

AFTER_MATCH = 'postfix'#

Lines after the match

class TextLine(*, line_number, line_content, match_type)[source]#

Bases: object

Represents a line of text with information on how it relates to the match.

Parameters:

  • line_number (int)

  • line_content (str)

  • match_type (LineType)

match_type: LineType#

Represents the type of line (match, prefix, postfix)

get_display_prefix()[source]#

Get the display prefix for this line based on the match type.

Return type:

str

format_line(include_line_numbers=True)[source]#

Format the line for display (e.g.,for logging or passing to an LLM).

Parameters:

include_line_numbers (bool) – Whether to include the line number in the result.

Return type:

str

class MatchedConsecutiveLines(
*,
lines,
source_file_path=None,
lines_before_matched=<factory>,
matched_lines=<factory>,
lines_after_matched=<factory>,
)[source]#

Bases: object

Represents a collection of consecutive lines found through some criterion in a text file or a string. May include lines before, after, and matched.

Parameters:

  • lines (list[TextLine])

  • source_file_path (str | None)

  • lines_before_matched (list[TextLine])

  • matched_lines (list[TextLine])

  • lines_after_matched (list[TextLine])

lines: list[TextLine]#

All lines in the context of the match. At least one of them is of match_type MATCH.

source_file_path: str | None = None#

Path to the file where the match was found (Metadata).

search_text(
pattern,
content=None,
source_file_path=None,
context_lines_before=0,
context_lines_after=0,
multiline=True,
)[source]#

Search for a pattern in text content. Supports both regex and glob-like patterns.

Parameters:

  • pattern (str) – Pattern to search for (regex or glob-like pattern)

  • content (str | None) – The text content to search. May be None if source_file_path is provided.

  • source_file_path (str | None) – Optional path to the source file. If content is None, this has to be passed and the file will be read.

  • context_lines_before (int) – Number of context lines to include before matches

  • context_lines_after (int) – Number of context lines to include after matches

  • multiline (bool) – whether to apply multi-line matching, enabling the flags re.DOTALL and re.MULTILINE

Returns:

List of TextSearchMatch objects

Raises:

ValueError if the pattern is not valid

Return type:

list[MatchedConsecutiveLines]

class GlobMatcher(expr)[source]#

Bases: ToStringMixin

Supports matching a file path against a glob pattern.

Supports standard glob patterns:

  • * matches any number of characters except /

  • ** matches any number of directories (zero or more)

  • ? matches a single character except /

  • [seq] matches any character in seq

Supports brace expansion:

  • {a,b,c} expands to multiple patterns (including nesting)

Parameters:

expr (str) – a glob pattern which may make use of brace expansion (e.g., "src/**/*.{js,jsx,ts,tsx}")

search_files(
file_collection,
pattern,
context_lines_before=0,
context_lines_after=0,
paths_include_glob=None,
paths_exclude_glob=None,
multiline=True,
)[source]#

Search for a pattern in a list of files.

Parameters:

  • file_collection (FileCollection) – the collection of files to search (will be optionally filtered by glob patterns)

  • pattern (str) – pattern to search for

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

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

  • paths_include_glob (str | None) – optional glob pattern to include files from the list

  • paths_exclude_glob (str | None) – optional glob pattern to exclude files from the list

  • multiline (bool) – whether to apply multi-line matching, enabling the flags re.DOTALL and re.MULTILINE (default: True)

Returns:

list of MatchedConsecutiveLines objects

Return type:

list[MatchedConsecutiveLines]

render_html(html)[source]#

Remove HTML tags and decode HTML entities from text while preserving the actual content. This keeps type information and structure but removes all formatting.

Parameters:

html (str) – HTML text to clean

Returns:

Plain text without HTML tags and with decoded entities

Return type:

str

class ContentReplacer(mode, allow_multiple_occurrences, regex_multiline=True)[source]#

Bases: object

This is an LLM-optimised content replacer, which elegantly circumvents escaping and which provides dual modes for maximum flexibility.

Parameters:

  • mode (Literal['literal', 'regex']) – the mode indicating whether to the needle in replacements corresponds to a regular expression (mode “regex”) or to a literal string (mode “literal”)

  • allow_multiple_occurrences (bool) – whether it is allowed that the search expression matches multiple occurrences. If False, an error will be raised if more than one match is found.

  • regex_multiline (bool) – whether to apply multi-line regex matching, enabling the flags re.DOTALL and re.MULTILINE

replace(content, needle, repl)[source]#

Performs the replacement.

Raises ValueError if no match is found, or if multiple matches are found while allow_multiple_occurrences is False.

Parameters:

  • content (str) – the content in which to perform the replacement

  • needle (str) – the search expression, which is either a literal string or a regular expression, depending on the mode

  • repl (str) – the replacement string, which, in regex mode, may contain backreferences in the form of $!1, $!2, etc. to refer to matched groups in the search expression

Returns:

the updated content after performing the replacement

Return type:

str

class ReplacementOccurrence(
occurrence_id,
relative_path,
index_in_file,
start,
end,
matched_text,
replacement,
start_line,
end_line,
is_ambiguous=False,
)[source]#

Bases: object

A single prospective replacement of a pattern match within one file.

Parameters:

  • occurrence_id (str)

  • relative_path (str)

  • index_in_file (int)

  • start (int)

  • end (int)

  • matched_text (str)

  • replacement (str)

  • start_line (int)

  • end_line (int)

  • is_ambiguous (bool)

occurrence_id: str#

stable, content-anchored identifier: ‘<relative_path>:<index_in_file>@<digest>’

index_in_file: int#

0-based index of this match among the matches within its file (in position order)

start: int#

character offset of the match start within the file content

end: int#

character offset of the match end within the file content

replacement: str#

the fully expanded replacement text (backreferences already resolved)

start_line: int#

0-based line number of the match start

end_line: int#

0-based line number of the match end

is_ambiguous: bool = False#

whether the pattern matches again within the matched text (possible over-match)

class MultiFileContentReplacer(mode, regex_multiline=True)[source]#

Bases: object

Occurrence-level counterpart of ContentReplacer operating on multiple files: finds every match of a pattern across a set of file contents, assigns each occurrence a stable content-anchored id, renders minimal line diffs for previewing, and computes the updated content of a file for a selected subset of occurrences.

Parameters:

  • mode (Literal['literal', 'regex']) – whether the needle is a literal string (“literal”) or a regular expression (“regex”)

  • regex_multiline (bool) – whether to apply multi-line regex matching, enabling the flags re.DOTALL and re.MULTILINE

find_occurrences(files, needle, repl)[source]#

Finds all matches of the needle in the given files.

Parameters:

  • files (list[tuple[str, str]]) – (relative_path, content) pairs; processed in the given order

  • needle (str) – the search expression (literal string or regex, depending on the mode)

  • repl (str) – the replacement template (may contain $!N backreferences in regex mode)

Returns:

occurrences in deterministic order (file order, then position within the file)

Return type:

list[ReplacementOccurrence]

static apply_to_content(content, occurrences)[source]#

Applies the given occurrences (which must have been derived from exactly this content) and returns the updated content.

Parameters:
Return type:

str

render_occurrence_diff(
occ,
content,
max_lines_per_side=6,
max_line_chars=200,
)[source]#

Renders a minimal line diff for the occurrence: the full lines spanned by the match, before and after the replacement.

Parameters:

  • occ (ReplacementOccurrence) – the occurrence (must have been derived from exactly this content)

  • content (str) – the file content the occurrence was found in

  • max_lines_per_side (int) – cap on the number of displayed lines per diff side

  • max_line_chars (int) – cap on the number of displayed characters per line

Returns:

the rendered diff

Return type:

str

class TextCoords(line: int, col: int)[source]#

Bases: object

Parameters:

  • line (int)

  • col (int)

line: int#

0-based line number

col: int#

0-based column number

find_text_coordinates(content, regex, require_unique=False)[source]#

Finds the line and column number of the first match of a regex pattern in the given content.

Parameters:

  • content (str) – the text content to search through

  • regex (str) – the regular expression pattern to search for; it must match part of a single line, and contain exactly one group that captures the position of interest (e.g., the exact variable name to find the coordinates of)

  • require_unique (bool) – if True, raises an error if not exactly one match is found; if False, returns None if no match is found, and returns the coordinates of the first match if multiple matches are found

Returns:

the coordinates of the match or None

Return type:

TextCoords | None