Python API#

Synopsis#

import real and use it like re – the same functions, the same Pattern / Match shapes, rendered here from the binding’s own docstrings (the text help() shows). Everything runs on the linear-time, ReDoS-safe engine by default; the opt-in fallback policy delegates a pattern REAL would reject to the standard-library re and forfeits that guarantee for it – Pattern.engine reports which backend ran. The extensions beyond re say so in their docstrings (count_matches, the fallback policy, RegexSet).

Functions#

real.compile(pattern, flags=0, fallback=None)#

Compile a regular expression pattern.

Mirrors re.compile. If pattern is already a compiled pattern, it is returned as-is and flags must be zero.

Parameters:

pattern (str, bytes, or Pattern) – The regular expression to compile.
flags (int, optional) – Bitwise OR of flags such as IGNORECASE, MULTILINE, DOTALL, VERBOSE. Defaults to 0.
fallback (bool, optional) – Policy for a pattern the linear engine cannot represent. None (default) uses the module-level real.fallback (itself False = strict). True delegates such a pattern to the standard library re (forfeiting the linear-time guarantee); False re-raises error. Extension beyond re.

Returns:

A compiled pattern — native (engine == "real") or, on fallback, an re-backed proxy (engine == "re").

Return type:

Pattern

Raises:

ValueError – If pattern is a compiled pattern and flags is non-zero.
error – If the pattern is invalid, or unsupported and the policy is strict.

real.match(pattern, string, flags=0)#

Apply match() using a compiled pattern.

Mirrors re.match: tries to match only at the beginning of string.

Parameters:

pattern (str or bytes) – Regular expression pattern.
string (str or bytes) – Text to match against.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

A match object on success, None otherwise.

Return type:

Match or None

real.fullmatch(pattern, string, flags=0)#

Apply fullmatch() using a compiled pattern.

Mirrors re.fullmatch: tries to match the entirety of string.

Parameters:

pattern (str or bytes) – Regular expression pattern.
string (str or bytes) – Text to match against.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

A match object on success, None otherwise.

Return type:

Match or None

real.search(pattern, string, flags=0)#

Apply search() using a compiled pattern.

Mirrors re.search: scans string for the leftmost match.

Parameters:

pattern (str or bytes) – Regular expression pattern.
string (str or bytes) – Text to search.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

A match object on success, None otherwise.

Return type:

Match or None

real.findall(pattern, string, flags=0)#

Apply findall() using a compiled pattern.

Mirrors re.findall: returns all non-overlapping matches.

Parameters:

pattern (str or bytes) – Regular expression pattern.
string (str or bytes) – Text to search.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

List of strings, tuples, or groups depending on the pattern.

Return type:

list

real.count_matches(pattern, string, flags=0)#

Count non-overlapping matches without building Match objects.

Extension beyond re. Prefer this over len(findall(...)) or counting finditer when only the count matters.

Parameters:

pattern (str or bytes) – Regular expression pattern.
string (str or bytes) – Text to search.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

Number of non-overlapping matches.

Return type:

int

real.finditer(pattern, string, flags=0)#

Apply finditer() using a compiled pattern.

Mirrors re.finditer: yields Match objects lazily.

Parameters:

pattern (str or bytes) – Regular expression pattern.
string (str or bytes) – Text to search.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

Iterator of Match objects.

Return type:

iterator

real.split(pattern, string, maxsplit=0, flags=0)#

Apply split() using a compiled pattern.

Mirrors re.split: splits string by occurrences of pattern.

Parameters:

pattern (str or bytes) – Regular expression pattern.
string (str or bytes) – Text to split.
maxsplit (int, optional) – Maximum number of splits. 0 means no limit. Defaults to 0.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

List of substrings, with captured groups interleaved.

Return type:

list

real.sub(pattern, repl, string, count=0, flags=0)#

Apply sub() using a compiled pattern.

Mirrors re.sub: replaces occurrences of pattern in string.

Parameters:

pattern (str or bytes) – Regular expression pattern.
repl (str, bytes, or callable) – Replacement template or callable accepting a Match object.
string (str or bytes) – Text to modify.
count (int, optional) – Maximum number of replacements. 0 means all. Defaults to 0.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

The resulting string after replacements.

Return type:

str or bytes

real.subn(pattern, repl, string, count=0, flags=0)#

Apply subn() using a compiled pattern.

Mirrors re.subn: replaces occurrences and returns the count.

Parameters:

pattern (str or bytes) – Regular expression pattern.
repl (str, bytes, or callable) – Replacement template or callable accepting a Match object.
string (str or bytes) – Text to modify.
count (int, optional) – Maximum number of replacements. 0 means all. Defaults to 0.
flags (int, optional) – Compilation flags. Defaults to 0.

Returns:

(result, number_of_substitutions).

Return type:

tuple

real.escape(pattern)#

Escape special characters in a pattern (like re.escape).

Parameters:: pattern (str or bytes) – Input pattern.
Returns:: Escaped pattern with the same type as pattern.
Return type:: str or bytes

real.purge()#: Clear the compiled-pattern cache (like re.purge).

real.get_include()#

Return the directory to add to a C++ include path.

#include <real/real.hpp> resolves against this directory. The header-only C++ library is shipped inside the installed package, so a project can compile against REAL located through its Python install:

c++ -std=c++20 $(python -c “import real; print(real.get_include())”) …

Falls back to the repository’s include/ when imported from a source checkout.

Returns:: Absolute path to the include directory.
Return type:: str

real.get_config()#

Return metadata for embedding the C++ library.

Returns:: Mapping with keys version (str), include (str, see get_include()), and cxx_standard (str, the language standard the headers require).
Return type:: dict

exception real.error(msg, pattern=None, pos=None)#

Exception raised when a pattern is invalid or unsupported.

Subclasses re.error when re is available, so except re.error: also catches REAL’s errors.

Pattern#

The compiled pattern – the C++ basic_regex behind a re.Pattern face.

class real.Pattern#

A compiled REAL pattern, with the re.Pattern API.

Created by real.compile() – not instantiable directly. Matching is O(len(string)): guaranteed linear, never backtracks (ReDoS-safe).

count_matches(string, pos=0, endpos=9223372036854775807)#

Count non-overlapping matches in [pos, endpos) without building Match objects.

Extension beyond re. Prefer this over len(findall(…)) or sum(1 for _ in finditer(…)) when only the count matters.

Parameters:

string (str or bytes) – Text to search.
pos (int) – Where to start. Character offset for str, byte offset for bytes. Not a slice: A and ^ (without MULTILINE) still fail at pos > 0.
endpos (int) – Where the string is treated as ending; counting stops there.

Returns:

Number of non-overlapping matches.

Return type:

int

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

engine#: The backend – “real” (linear, ReDoS-safe) or “re” (fallback). Extension beyond re.

findall(string, pos=0, endpos=9223372036854775807)#

Return all non-overlapping matches in the region [pos, endpos).

Parameters:

string (str or bytes) – Text to search.
pos (int) – Where to start. Character offset for str, byte offset for bytes. Not a slice: A and ^ (without MULTILINE) still fail at pos > 0.
endpos (int) – Where the string is treated as ending; matches stop there.

Returns:

List of strings, bytes, or tuples depending on groups.

Return type:

list

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

finditer(string, pos=0, endpos=9223372036854775807)#

Return an iterator yielding Match objects for the region [pos, endpos).

Parameters:

string (str or bytes) – Text to search.
pos (int) – Where to start. Character offset for str, byte offset for bytes. Not a slice: A and ^ (without MULTILINE) still fail at pos > 0.
endpos (int) – Where the string is treated as ending; iteration stops there.

Returns:

Iterator over all matches (each carries the region’s .pos/.endpos).

Return type:

iterator

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

flags#: The compilation flags as passed to compile().

fullmatch(string, pos=0, endpos=9223372036854775807)#

Try to match the whole region [pos, endpos) of the string.

Parameters:

string (str or bytes) – Text to match.
pos (int) – Start. Character offset for str, byte offset for bytes.
endpos (int) – End of the region the match must span ($ and Z see it).

Returns:

Match object on success, None otherwise.

Return type:

Match or None

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

groupindex#: Mapping from group name to group number.

groups#: Number of capturing groups (excluding group 0).

match(string, pos=0, endpos=9223372036854775807)#

Try to match at position pos in the string.

Parameters:

string (str or bytes) – Text to match.
pos (int) – Where to start. Character offset for str, byte offset for bytes. Not a slice: A and ^ (without MULTILINE) still fail at pos > 0.
endpos (int) – Where the string is treated as ending ($ and Z see it).

Returns:

Match object on success, None otherwise.

Return type:

Match or None

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

pattern#: The pattern string or bytes used for compilation.

search(string, pos=0, endpos=9223372036854775807)#

Scan the region [pos, endpos) for the leftmost match.

Parameters:

string (str or bytes) – Text to search.
pos (int) – Where to start. Character offset for str, byte offset for bytes. Not a slice: A and ^ (without MULTILINE) still fail at pos > 0.
endpos (int) – Where the string is treated as ending ($ and Z see it).

Returns:

Match object on success, None otherwise.

Return type:

Match or None

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

split(string, maxsplit=0)#

Split the string by occurrences of the pattern.

Parameters:

string (str or bytes) – Text to split.
maxsplit (int, optional) – Maximum number of splits. 0 means no limit.

Returns:

Substrings with captured groups interleaved.

Return type:

list

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

sub(repl, string, count=0)#

Replace occurrences of the pattern in the string.

Parameters:

repl (str, bytes, or callable) – Replacement template or callable accepting a Match object.
string (str or bytes) – Text to modify.
count (int, optional) – Maximum replacements. 0 means all.

Returns:

Result after replacements.

Return type:

str or bytes

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

subn(repl, string, count=0)#

Replace occurrences and return the result plus the count.

Parameters:

repl (str, bytes, or callable) – Replacement template or callable.
string (str or bytes) – Text to modify.
count (int, optional) – Maximum replacements. 0 means all.

Returns:

(result, number_of_substitutions).

Return type:

tuple

Complexity

Matching is O(len(string)) – guaranteed linear; never backtracks (ReDoS-safe).

Match#

The result of a successful match – basic_match_result behind a re.Match face; finditer walks it through basic_match_range.

class real.Match#

The result of a successful match, with the re.Match API.

Returned by Pattern match/fullmatch/search/finditer – not instantiable directly. Supports m[group] subscripting; always truthy.

end(group=0, /)#

Return the end index of a group in the original string.

Parameters:: group (int or str, optional) – Group number or name. Defaults to 0.
Returns:: Character index where the group ends.
Return type:: int

endpos#: Effective endpos passed to the matching call (clamped; default len).

expand(template, /)#

Return the string obtained by backslash-substituting the template, exactly as sub() would for this match.

Parameters:

template (str or bytes) – A template with 1, g<name>, g<1>, g<0> (the whole match) and escapes. Must match the pattern’s str/bytes type.

Returns:

The expanded template. A group that did not participate: contributes nothing.

Return type:

str or bytes

group(*groups)#

Return the matched substring or subgroups.

Parameters:

group (int or str, optional) – Group number or name. Defaults to 0 (the whole match).

Returns:

The matched text, or None if the group did: not participate. Multiple arguments return a tuple.

Return type:

str or bytes or None

groupdict(default=None)#

Return a dictionary mapping group names to matched strings.

Parameters:: default – Value for groups that did not participate.
Returns:: {name: matched_text} for all named groups.
Return type:: dict

groups(default=None)#

Return a tuple of all subgroup strings.

Parameters:: default – Value for groups that did not participate.
Returns:: One entry per capturing group (group 1 onwards).
Return type:: tuple

lastgroup#: Name of the last matched capturing group, or None.

lastindex#: Index of the last matched capturing group, or None.

pos#: Effective pos passed to the matching call (clamped; default 0).

re#: The Pattern object that produced this match.

regs#: Tuple of (start, end) spans for the whole match and each group.

span(group=0, /)#

Return the (start, end) indices of a group.

Parameters:: group (int or str, optional) – Group number or name. Defaults to 0.
Returns:: (start, end) character indices.
Return type:: tuple

start(group=0, /)#

Return the start index of a group in the original string.

Parameters:: group (int or str, optional) – Group number or name. Defaults to 0.
Returns:: Character index where the group starts.
Return type:: int

string#: The string or bytes that was searched.

RegexSet#

Multi-pattern which-matched – the C++ regex_set from Python.

class real.RegexSet(patterns, flags=0)#

Multi-pattern which-matched set (RE2::Set / rust RegexSet style).

Extension beyond re.

Construction compiles every pattern (raises error if any fails — no silent skip). matches(text) returns a list of bools in construction order; is_match(text) is any-match (stops at the first hit). Captures are not reported — re-run the individual Pattern if groups are needed.

Wraps real::regex_set directly, not a Python loop over individual Pattern objects. The bitset is always in construction order.

is_match(string, pos=0, endpos=None)#: True if any pattern matches string (stops at the first hit).

matches(string, pos=0, endpos=None)#: Which patterns match at least once (construction-order list of bool).

which(string, pos=0, endpos=None)#: Indices of matching patterns (ascending, construction order).

Flags and module data#

The flag integers match re (real.I is 2, same as re.I). Pair aliases (I / IGNORECASE, …) are the same object.

Name	`re` twin	Meaning
`NOFLAG`	`re.NOFLAG`	No flags.
`I` / `IGNORECASE`	`re.I`	Case-insensitive (Unicode fold in text mode; ASCII under `A`).
`M` / `MULTILINE`	`re.M`	`^` and `$` also match at line boundaries.
`S` / `DOTALL`	`re.S`	`.` also matches a newline.
`X` / `VERBOSE`	`re.X`	Ignore unescaped whitespace and `#` comments outside classes.
`A` / `ASCII`	`re.A`	Keep `\w \d \s \b` and case folding ASCII, even in `str` mode.
`U` / `UNICODE`	`re.U`	No-op: Unicode is the `str`-mode default.

real.fallback: bool = False#: Module-level policy for a pattern the linear engine cannot represent (backreferences, conditionals, an unbounded lookaround). The default is strict: such a pattern raises error. Set real.fallback = True, or pass fallback=True to compile() / the module functions, to delegate that pattern to the standard-library re – which may accept it but forfeits the linear-time guarantee. A per-call argument wins.

Complexity#

Every pattern REAL accepts runs the engine the C++ pages document: matching is guaranteed linear – O(len(string)) – and never backtracks (ReDoS-safe), for str and bytes alike. The opt-in fallback=True (per call, or real.fallback = True) routes a pattern REAL rejects to the backtracking stdlib re, trading the linear-time guarantee for that pattern; Pattern.engine ("real" / "re") tells you which ran. The Python-vs-re numbers live in Performance.

Example#

Run by the Python test suite on every push – tested code, not an illustration:

import real as re   # drop-in for the standard library's re

m = re.search(r"(\w+)@(\w+)", "info@example.com")
m.group(2)                # 'example' — linear time, no backtracking cliff

Python API#

Synopsis#

Functions#

Pattern#

Match#

RegexSet#

Flags and module data#

Complexity#

Example#

See also#