Module-level functions

These module-level entry points mirror re and are thin adapters around the Rust extension. Each accepts either a str or pathlib.Path as the file path and dispatches on max_span_lines.

class file_re.core.file_re_cls

Static facade that exposes the public file_re API.

The class mirrors the module-level surface of re. Each method is a thin adapter over the Rust extension: it coerces Path inputs, validates max_span_lines, emits warnings for flags that diverge from re, and wraps results in Python Match objects.

static search(pattern, file_path, flags=0, *, max_span_lines=None)

Scan the file and return the first match anywhere.

Parameters:

• pattern (str) – The regex pattern to search for.

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

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

• 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, if pattern is invalid, or if flags contains re.LOCALE.

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

Examples

>>> from file_re import file_re
>>> m = file_re.search(r"ERROR: (\w+)", "server.log")
>>> m.group(1) if m else None

static match(pattern, file_path, flags=0, *, max_span_lines=None)

Match the pattern anchored at the start of the file.

Parameters:

• pattern (str) – The regex pattern to match.

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

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

• 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 not >= 1, if pattern is invalid, or if flags contains re.LOCALE.

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

static findall(pattern, file_path, flags=0, *, max_span_lines=None)

Return all non-overlapping matches in the file.

Parameters:

• pattern (str) – The regex pattern to search for.

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

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

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

Returns:

If 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 not >= 1, if pattern is invalid, or if flags contains re.LOCALE.

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

static finditer(pattern, file_path, flags=0, *, max_span_lines=None)

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

Parameters:

• pattern (str) – The regex pattern to search for.

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

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

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

Returns:

Yields Match objects lazily. 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 not >= 1, if pattern is invalid, or if flags contains re.LOCALE.

• OSError – If the file cannot be opened.

Examples

>>> from file_re import file_re
>>> for m in file_re.finditer(r"\bERROR\b", "server.log", max_span_lines=1):
...     print(m.span(), m.group())

static compile(pattern, flags=0)

Compile a regex pattern into a reusable Pattern object.

Parameters:

• pattern (str) – The regex source string.

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

Returns:

A compiled pattern that exposes search, match, findall, and finditer methods.

Return type:

Pattern

Raises:

ValueError – If pattern is invalid, or if flags contains re.LOCALE.