mrab-regex

regex is a mature alternative to Python’s built-in re module, maintained as a superset that stays backwards-compatible while extending what the standard library can do. Under the covers it’s a C extension (the bulk of the codebase is C, not Python) wrapped by a thin Python front-end, which is why it keeps pace with re’s performance while adding features CPython has never shipped.

The headline additions are approximate (“fuzzy”) matching with configurable insertion/substitution/deletion budgets, nested character sets with set algebra (union, intersection, difference), recursive and named-group back-references, variable-length lookbehind, and both simple and full Unicode case-folding. A VERSION0/VERSION1 flag lets callers pin the old re-compatible behavior or opt into the newer, corrected semantics (e.g. properly handled zero-width matches) without breaking existing code.

Because it mirrors the re API almost exactly, most projects adopt it with a single import swap (import regex as re), then progressively opt into the extended syntax where it earns its keep — log scrubbing and OCR text cleanup with fuzzy matching, Unicode-aware tokenization, or patterns too intricate for re’s more limited grammar.

What You Get

• A near drop-in replacement for re — most code migrates with a single import change
• Approximate/fuzzy matching with explicit limits on substitutions, insertions, and deletions per match
• Nested character sets with set operators (union ||, intersection &&, difference --)
• Recursive patterns ((?R), (?1), (?&name)) for matching balanced or self-referential structures
• Variable-length lookbehind assertions, unlike re’s fixed-width-only lookbehind
• Full Unicode case-folding in addition to re’s simple case-folding
• VERSION0/VERSION1 flags to choose between re-compatible and corrected/enhanced behavior explicitly

Common Use Cases

• Migrating existing re-based code to gain performance or bug fixes with minimal changes
• Fuzzy-matching noisy text such as OCR output, user-entered data, or log lines with typos
• Parsing nested or balanced constructs (brackets, tags) via recursive group references
• Unicode-heavy text processing that needs full case-folding across scripts
• Building tokenizers or validators that need set algebra inside character classes

Under The Hood

Architecture

The project is a thin-Python-over-C design: regex/_main.py and regex/_regex_core.py implement pattern compilation, flag handling, and the public API surface (compile, match, search, sub, split, and friends), while the actual matching engine lives in src/_regex.c and src/_regex_unicode.c — together over 26,000 lines of C, roughly 86% of the codebase by bytes. Python owns parsing and orchestration; C owns the hot-path matching loop, which is what lets fuzzy and recursive matching run at competitive speed instead of falling back to a pure-Python backtracker.

Tech Stack

Built with setuptools (pyproject.toml + setup.py) compiling a single C extension module (regex._regex) against src/_regex.c and src/_regex_unicode.c, with a Py_GIL_DISABLED macro path for free-threaded CPython builds. No runtime dependencies — it targets CPython specifically (the README notes it doesn’t behave correctly on PyPy due to string-representation differences) and supports Python 3.10 through the upcoming 3.15 line per its classifiers.

Code Quality

Testing runs through the standard-library unittest framework against a single large suite (regex/tests/test_regex.py, ~4,500 lines) exercising both VERSION0 and VERSION1 behavior paths, and CI (cibuildwheel GitHub Actions workflow) runs that suite across Ubuntu, macOS, and Windows for every tagged release, plus builds and tests wheels for CPython 3.10 through 3.15 (including free-threaded variants). There’s no separate linter/formatter configuration checked in, and as a C-extension project it doesn’t use Python type hints, but the extensive single-file test suite and multi-platform wheel-build matrix substitute for that kind of tooling.

What Makes It Unique

What sets regex apart from re and from most other regex engines is that it doesn’t trade off compatibility for features — it defaults to re-identical behavior (VERSION0) and only exposes fuzzy matching, nested sets, and recursive patterns when a caller opts in via flags or syntax, so existing re patterns keep working unchanged. The fuzzy-matching implementation in particular — configurable per-error-type budgets with BESTMATCH/ENHANCEMATCH refinement flags and introspectable fuzzy_counts/fuzzy_changes results — goes well beyond what most “approximate matching” libraries expose, since it stays exposed through the same compiled-pattern API as ordinary matching.