asweigart/humre

Humre

A human-readable regular expression module for Python. Humre handles regex syntax for you and creates regex strings to pass to Python's re.compile(). Pronounced "hum, ree".

It is similar to Swift's regex DSL or an advanced form of Python regex's re.VERBOSE mode. Code is read far more often than it is written, so the verbose Humre code may take a few seconds longer to write but pays for itself by being much easier to read and understand.

Note that until version 1.0 is released, the API for this module could change. Please send suggestions and feedback to [email protected].

Quickstart

>>> from humre import *
>>> regexStr = either(OPEN_PAREN + exactly(3, DIGIT) + CLOSE_PAREN, exactly(3, DIGIT)) + '-' + exactly(3, DIGIT) + '-' + exactly(4, DIGIT)
>>> regexStr
'\\(\\d{3}\\)|\\d{3}-\\d{3}-\\d{4}'
>>> patternObj = compile(regexStr)
>>> matchObj = patternObj.search('Call 415-555-1234 today!')
>>> matchObj
<re.Match object; span=(5, 17), match='415-555-1234'>
>>> matchObj.group()
'415-555-1234'

Frequently Asked Questions

What Does Humre Provide?

Humre provides a collection of functions and constants to create regex strings without having to know the specific regex symbols. These offer more structure and readability than regex strings.

Do I Need to Know Regular Expressions to Use Humre?

Yes and no. You still need to know what regular expressions are and how they're used. But instead of memorizing the punctuation marks for each regex feature you want to use, you can use the easier-to-remember Humre functions and constants. For example, zero_or_more(chars('a-z')) is easier to remember than [a-z]* if you are inexperienced with regex. But I recommend reading a general regex tutorial before using Humre.

What's Wrong with Python's re Module?

It's more what's wrong with regular expression syntax. Regex strings can look like a cryptic mess of punctuation marks, and even if you're an experienced software engineer, complex regex strings can be hard to read and debug.

Doesn't Verbose Mode Fix That Problem?

A little. But because verbose mode still has the regex string as a string value, dev tools such as linters, syntax highlighting, and matching parentheses highlighting can't be employed. Also, dealing with escape characters can still be a pain.

Is Humre a New Reimplementation of Python's re Module?

No. Humre only creates the regex strings to pass to re.compile() (or to pass to humre.compile() which wraps it.)

What Are Benefits of Using Humre Instead of Writing My Own Regex Strings?

• Your editor's parentheses matching works.
• Your editor's syntax highlight works.
• Your editor's linter and type hints tool picks up typos.
• Your editor's autocomplete works.
• Auto-formatter tools like Black can automatically format your regex code.
• Humre handles raw strings/string escaping for you.
• You can put actual Python comments alongside your Humre code.
• Better error messages for invalid regexes.

Is It A Good Idea To Use The from humre import * Importing Syntax?

In this case, sure. Generally this form importing is frowned on, but it'll keep your optional(group('cat' + DIGIT)) code from becoming humre.optional(humre.group('cat' + humre.DIGIT)). Note that this will overwrite the (infrequently-used) built-in compile() function with humre.compile(), which is a wrapper for re.compile().

How Do I Combine Humre's Functions and Constants Together?

Every Humre function returns a regex string and every Humre constant is a string, so you can use f-strings and string concatenation to combine them:

>>> from humre import *

>>> exactly(5, DIGIT) + optional(WHITESPACE) + one_or_more(NONWHITESPACE)
'\\d{5}\\s?\\S+'

>>> 'I am looking for %s grapes.' % (exactly(2, DIGIT))
'I am looking for \\d{2} grapes.'

>>> f'I am looking for {exactly(2, DIGIT)} grapes.''
'I am looking for \\d{2} grapes.'

Humre Seems Nice for Beginners, But Why Would Experienced Devs Want to Use It?

TODO

Why Is the humre.compile() Function Not Working When I Pass Flags to It?

Most Humre functions combine their arguments into one string for ease of use (that is, group('cat', 'dog') is the same as group('catdog')). The humre.compile() function does this to, so if you want to pass flags such as

Isn't Using Humre a Performance Hit Compared to Using re?

No. Humre functions are simple functions that do basic string manipulation. You only need to call them once when you create the regex pattern object. Your program, whether large or small, will spend far more time doing the actual pattern matching than creating the regex string.

Most Regexes Are Short Enough That the Syntax Doesn't Get In the Way. Why Use Humre for These?

Sure, the phone number example is simple enough that anyone who knows regex syntax can understand it.

Humre vs re Comparison

Here's a comparison of the code for Python's re module versus the equivalent code with Humre (formatted with the Black code-formatting tool.)

American Phone Number with re:

import re
re.compile('\d{3}-\d{3}-\d{4}')

American Phone Number with Humre:

from humre import *
compile(exactly(3, DIGIT), "-", exactly(3, DIGIT), "-", exactly(4, DIGIT))

Hexadecimal Number with Optional Leading 0x or 0X and Consistent Casing with re:

import re
re.compile('(?:(?:0x|0X)[0-9a-f]+)|(?:(?:0x|0X)[0-9A-F]+)|(?:[0-9a-f]+)|(?:[0-9A-F]+)')

Hexadecimal Number with Optional Leading 0x or 0X and Consistent Casing with re:

from humre import *
compile(
    either(
        noncap_group(noncap_group(either('0x', '0X')), one_or_more(chars('0-9a-f'))),
        noncap_group(noncap_group(either('0x', '0X')), one_or_more(chars('0-9A-F'))),
        noncap_group(one_or_more(chars('0-9a-f'))),
        noncap_group(one_or_more(chars('0-9A-F')))
    )
)

Number with or without comma-formatting including decimal point with re:

import re
re.compile(r'(?:\+|-)?(?:(?:\d{1,3}(?:,\d{3})+)|\d+)(?:\.\d+)?')

Number with or without comma-formatting including decimal point with Humre:

from humre import *
compile(
    # optional negative or positive sign:
    optional(noncap_group(either(PLUS_SIGN, '-'))),
    # whole number section:
    noncap_group(either(
        # number with commas:
        noncap_group(between(1, 3, DIGIT), one_or_more(noncap_group(',', exactly(3, DIGIT)))),
        # number without commas:
        one_or_more(DIGIT)
    )),
    # fractional number section (optional)
    optional(noncap_group(PERIOD, one_or_more(DIGIT)))
    )

Or you can use Humre's included NUMBER pattern:

from humre import *
compile(NUMBER)

Quick Reference

Here's a quick list of all of Humre's functions and constants, and the regex strings that they produce:

The convenience group functions combine a Humre function with the group() (or noncap_group()) function since putting regexes in groups is so common, such as with ([A-Z])+ putting the character class

Humre provides constants for the \d, \w, and \s character classes as well several other characters that need to be escaped:

Humre also provides constants for commonly used patterns:

Humre's compile() function's flags keyword argument takes the same flag values as re.compile():