Pattern

class file_re.Pattern(pattern, flags=0)

Bases: object

A compiled regex pattern, mirroring re.Pattern.

Instances are produced by file_re.compile() and hold a compiled Rust regex. The compiled pattern is reused across calls, avoiding recompilation overhead for patterns applied to multiple files.

Parameters:

• pattern (str) – The regex source string.

• flags (int, optional) – Bitwise OR of re flags. Defaults to 0.

Raises:

ValueError – If pattern is not a valid regex, or if flags contains re.LOCALE.

__init__(pattern, flags=0)

Parameters:

• pattern (str)

• flags (int)

property pattern: str

The regex source string used to compile this pattern.

Returns:

The original pattern string.

Return type:

str

property flags: int

The flags used to compile this pattern.

Returns:

Bitwise OR of the re flags supplied at compile time.

Return type:

int

search(file_path, max_span_lines=None)

Scan the file and return the first match anywhere.

Parameters:

• file_path (str or pathlib.Path) – Path to the target file. Gzip (.gz) and xz (.xz) archives are decoded transparently.

• max_span_lines (int or None, optional) – Controls how much of the file is held in memory. None (default) loads the whole file; 1 scans line by line; N > 1 uses a sliding N-line window.

Returns:

The first match, or None if no match is found.

Return type:

Match or None

Raises:

• ValueError – If max_span_lines is provided and not >= 1.

• OSError – If the file cannot be opened or read.

match(file_path, max_span_lines=None)

Match the pattern anchored at the start of the file.

Parameters:

• file_path (str or pathlib.Path) – Path to the target file.

• max_span_lines (int or None, optional) – See search().

Returns:

The match, or None if the pattern does not match at position 0.

Return type:

Match or None

Raises:

• ValueError – If max_span_lines is provided and not >= 1.

• OSError – If the file cannot be opened or read.

findall(file_path, max_span_lines=None)

Return all non-overlapping matches in the file.

Parameters:

• file_path (str or pathlib.Path) – Path to the target file.

• max_span_lines (int or None, optional) – See search().

Returns:

If the pattern has no capturing groups, a list of match strings. Otherwise, a list of tuples containing the captured groups (non-participating groups are None).

Return type:

list

Raises:

• ValueError – If max_span_lines is provided and not >= 1.

• OSError – If the file cannot be opened or read.

finditer(file_path, max_span_lines=None)

Iterate lazily over all non-overlapping matches in the file.

Parameters:

• file_path (str or pathlib.Path) – Path to the target file.

• max_span_lines (int or None, optional) – See search().

Returns:

A lazy iterator that yields Match objects. The underlying file is closed when the iterator is exhausted or garbage collected.

Return type:

Iterator of Match

Raises:

• ValueError – If max_span_lines is provided and not >= 1.

• OSError – If the file cannot be opened.

__repr__()

Return repr(self).

Return type:

str