regexonic

A more Pythonic extension of Python's builtin re module.

import regexonic as re

Serves as a drop-in replacement for the builtin re library—all standard re functions, constants, and classes are re-exported.

Installation

pip install regexonic

OR

uv add regexonic

Purpose

The standard re module works well, but has some rough edges:

• Methods return None on failure, requiring constant null checks
• No built-in way to raise exceptions on match failure
• Type hints could be more precise for IDE support
• Common patterns like "validate or raise" require boilerplate

regexonic provides a thin wrapper that addresses these issues while maintaining full compatibility with the standard library.

Usage

import regexonic as re

# Create a pattern using the helper function
email = re.define(r"[\w.-]+@[\w.-]+\.\w+")

# Or use the class directly
email = re.Expression(r"[\w.-]+@[\w.-]+\.\w+")

# Boolean checking
email.check("user@example.com")  # True
email.check("invalid-email")     # False

# Get match or None (standard behavior)
email.match("user@example.com")  # <re.Match object>
email.match("invalid-email")     # None

# Get match or raise exception
email.match("user@example.com", required=True)  # <re.Match object>
email.match("invalid-email", required=True)     # Raises MatchNotFoundError

# Validate and return the string
email.validate("user@example.com")  # "user@example.com"
email.validate("invalid-email")     # Raises ValueError

Core Classes

Expression

A drop-in replacement for re.Pattern with enhanced functionality.

import regexonic as re

pattern = re.Expression(r"\d{3}-\d{4}", flags=re.IGNORECASE)

# All standard re.Pattern methods are available
pattern.search("Call 555-1234 today")
pattern.findall("555-1234 or 555-5678")
pattern.sub("XXX-XXXX", "Call 555-1234")
pattern.split("a-555-1234-b")

# Enhanced methods with `required` parameter
pattern.search("no numbers here", required=True)  # Raises SearchNotFoundError
pattern.match("555-1234", required=True)          # Returns match or raises MatchNotFoundError

# Convenience methods
pattern.check("555-1234")              # True (full match by default)
pattern.check("555-1234", full=False)  # True (partial match)
pattern.test("555-1234")               # Alias for check()
pattern.validate("555-1234")           # Returns string or raises ValueError

Structure

A base class for creating reusable pattern classes with custom methods.

import regexonic as re

class PhoneNumber(re.Structure):
    compiled = re.compile(r"(?P<area>\d{3})-(?P<exchange>\d{3})-(?P<number>\d{4})")
    
    @classmethod
    def parse(cls, string: str) -> dict[str, str]:
        match = cls.fullmatch(string, required=True)
        return match.groupdict()
    
    @classmethod
    def format(cls, string: str) -> str:
        groups = cls.parse(string)
        return f"({groups['area']}) {groups['exchange']}-{groups['number']}"

PhoneNumber.check("555-123-4567")      # True
PhoneNumber.parse("555-123-4567")      # {'area': '555', 'exchange': '123', 'number': '4567'}
PhoneNumber.format("555-123-4567")     # "(555) 123-4567"

Matcher

A lightweight callable class optimized for boolean matching.

import regexonic as re

is_hex_color = re.Matcher(r"#[0-9A-Fa-f]{6}")

is_hex_color("#FF5733")  # True
is_hex_color("red")      # False

# Get the actual match object when needed
is_hex_color.get("#FF5733")                  # <re.Match object>
is_hex_color.get("red", required=True)       # Raises MatchNotFoundError

Subber

A callable wrapper for substitution operations.

import regexonic as re

censor = re.Subber("***", r"\b(bad|ugly|evil)\b", flags=re.IGNORECASE)

censor("That was a bad idea")   # "That was a *** idea"
censor("Bad BAD bad", count=2)  # "*** *** bad"
censor.n("Bad BAD bad")         # ("*** *** ***", 3) - returns count too

Exception Handling

regexonic provides descriptive exceptions when matches fail:

import regexonic as re

pattern = re.define(r"\d+")

try:
    pattern.match("no digits", required=True)
except re.MatchNotFoundError as e:
    print(e.pattern)   # The regex pattern
    print(e.input)     # The input string
    print(e.detail)    # Human-readable message

Type Safety

All classes are generic and support both str and bytes patterns:

import regexonic as re

# String patterns
str_pattern: re.Expression[str] = re.Expression(r"\w+")
str_pattern.match("hello")  # Match[str]

# Bytes patterns
bytes_pattern: re.Expression[bytes] = re.Expression(rb"\w+")
bytes_pattern.match(b"hello")  # Match[bytes]

API Reference

Expression Methods

Re-exported from re

All standard re module exports are available:

• Functions: compile, search, match, fullmatch, split, findall, finditer, sub, subn, escape, purge
• Constants: ASCII/A, IGNORECASE/I, LOCALE/L, MULTILINE/M, DOTALL/S, UNICODE/U, VERBOSE/X, NOFLAG
• Classes: Pattern, Match, RegexFlag, error

License

MIT