backrefs

library8.0pypypi✓ verified 25d ago

backrefs is a Python library that extends the functionality of the standard `re` module and the third-party `regex` module by adding additional back references. It introduces features like `\c` for character class back-references, `\k<name>` for named capture groups that act as character classes, and enhanced atomic grouping. The library maintains an active development status, with regular minor releases addressing new features, bug fixes, and Python version compatibility.

serialization

pip install backrefs

github ↗package ↗

INSTALL

IMPORT

SIG · BACKREFS

backrefs

serializationpythonv8.0

Install

1.6s avg

Import

21ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.024s · 20.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.018s · 21MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bre

✓ from backrefs import bre

✗ import backrefs.bre as bre

While 'import backrefs.bre as bre' works, the direct 'from backrefs import bre' is idiomatic and commonly used in examples.

bregex

✓ from backrefs import bregex

✗ import backrefs.bregex as bregex

Similar to `bre`, direct import is idiomatic. Remember that `bregex` requires the `regex` package to be installed.

This quickstart demonstrates how to use `backrefs.bre` to leverage character class back-references (e.g., `\c1` or `\k<name>`), a powerful feature not available in Python's standard `re` module. The example shows searching for repeating words and replacing them.

import os from backrefs import bre # Example demonstrating character class back-references (\c) # Standard 're' does not support directly referencing a captured group as a character class. text = "apple banana banana orange" # Pattern to match a word followed by a space and then the same word, # using \c1 to reference the first captured group as a character class. pattern_with_c = r'(\b\w+\b)\s\c1' # Using backrefs.bre (which extends the standard 're' module) match = bre.search(pattern_with_c, text) if match: print(f"Matched: '{match.group(0)}'") print(f"First word captured: '{match.group(1)}'") else: print("No match found.") # Another example: replacing duplicate consecutive words text_dupe = "hello hello world world test" pattern_dupe = r'(\b\w+\b)\s\c1' # Replace "word word" with just "word" result = bre.sub(pattern_dupe, r'\1', text_dupe) print(f"Original: '{text_dupe}'") print(f"After replacing duplicates: '{result}'")

Debug

Known issues

breakingIn version 6.0, the behavior of POSIX character classes (e.g., `[[:alnum:]]`, `[[:digit:]]`) was changed to always use POSIX compatibility rules instead of Unicode standard rules where applicable. This might break existing patterns that relied on the previous Unicode standard behavior for these classes.

fix

To explicitly use standard Unicode rules for affected properties, use their Unicode property form instead (e.g., `[\p{Alnum}]` instead of `[[:alnum:]]`). Review and test existing regex patterns carefully after upgrading.

affects: 6.0 and later

breakingPython 3.8 support was officially dropped in version 5.8. Users on Python 3.8 or older will need to upgrade their Python version or stay on backrefs < 5.8.

fix

Upgrade your Python environment to 3.9 or newer to use backrefs 5.8+.

affects: 5.8 and later

gotchabackrefs provides two main interfaces: `bre` and `bregex`. `bre` wraps Python's built-in `re` module, while `bregex` wraps the third-party `regex` module. `bregex` offers more advanced regex features (inherited from `regex`) but requires `pip install regex`.

fix

Choose the appropriate module (`bre` or `bregex`) based on your needs and installed dependencies. If you need features from the `regex` library (e.g., fuzzy matching, recursion), use `bregex` and ensure `regex` is installed.

affects: All versions

gotchaA regression in version 6.0 created an ASCII binary property that would override an ASCII block property, leading to incorrect matching behavior in specific scenarios.

fix

This issue was fixed in version 6.0.1. Users on 6.0 should upgrade to 6.0.1 or newer to avoid this specific regression.

affects: 6.0

breakingThe `bre` interface uses Python's built-in `re` module, which does not support `\c` as a standalone escape sequence (e.g., for control characters or as a literal backslash followed by 'c'). Using `\c` directly in a pattern will result in `re.error: bad escape \c`.

fix

To match a literal `\c`, escape the backslash: use `\\c`. If you intended to match a control character (e.g., `\cA`), Python's `re` module does not support this syntax; you must use the actual character value (e.g., `\x01` for Ctrl+A). Note that `backrefs` *does* interpret `\c<name>` as a named backreference.

affects: All versions

gotchaThe `backrefs.bre` interface, which wraps Python's built-in `re` module, does not support the `\c` escape sequence in regular expression patterns. This will result in an `re.PatternError`.

fix

Do not use `\c` in patterns with `backrefs.bre`. If you need to match a literal 'c', use 'c'. If you intended a control character, use the appropriate hexadecimal (`\xNN`) or Unicode (`\uNNNN`) escape, or the character directly.

affects: All versions

Errors

Common errors & fixes

ImportError: cannot import name 're' from 'backrefs'

Developers often try to import Python's standard `re` module directly from `backrefs`, but the `backrefs` library wraps `re` and exposes its extended functionality under the name `bre`.

fix

Use `from backrefs import bre` to import the `backrefs` wrapper for the `re` module, or `from backrefs import bref` for the `regex` module wrapper.

re.error: invalid group reference

This error occurs when a backreference within a regular expression pattern, such as `\1`, `\k<name>`, or the `backrefs`-specific `\c`, refers to a capturing group that does not exist or is out of scope. This can be particularly an issue when misusing the new `\k<name>` or `\c` features of `backrefs` without defining the corresponding named group or character class.

fix

Review the regular expression pattern to ensure all backreferences correctly correspond to an existing capturing group. For named backreferences (`\k<name>`), verify that the named group has been defined (e.g., `(?P<name>...)`). Always use raw strings (e.g., `r'pattern'`) for regular expressions to avoid issues with Python's string literal escaping.

ModuleNotFoundError: No module named 'backrefs'

The `backrefs` library is not installed in the Python environment where the code is being executed.

fix

Install the `backrefs` library using pip: `pip install backrefs`.

Upgrade

Version history

8.0latest on PyPI · released Jul 26, 2026

Audit

Dependencies

regexoptionalRequired if using `backrefs.bregex` for advanced regex features beyond what `re` offers.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/facelessuser/backrefs ↗

packagehttps://pypi.org/project/backrefs/ ↗