ecma-regex

ECMA-262 regular expressions for Python: parse them, translate them to re (or regex), and match with JavaScript semantics.

Several widely used data formats specify their regular expressions as ECMA-262 patterns — JSON Schema above all. A Python program that hands those patterns straight to re does not get an error; it gets different answers, quietly, for ^, $, ., \d, \w, \s and \b, and a hard failure for \p{...}. This package closes that gap.

It has no dependencies and imports nothing from any consumer. It happens to power json-schema-engine, but it does not depend on it, and it is useful anywhere an ECMA-262 pattern has to run under Python.

Produced by Henry Andrews via Claude Code.

Status: 0.0.x. The implementation is functional and tested against every regular expression in the official JSON Schema test suite, but the documentation is AI-written and not yet audited against actual usage or human readability standards. 0.1.x ships once the documentation is deemed suitable for general consumption.

Install

pip install ecma-regex
# optional: the `regex` backend, which adds variable-width lookbehind
# and native \p{Script=...} support
pip install 'ecma-regex[regex]'

Python 3.12+.

Usage

import ecma_regex

pattern = ecma_regex.compile(r"^\p{Letter}+$")
pattern.search("olé")  # True
pattern.search("olé1")  # False
pattern.translated  # the emitted `re` pattern
pattern.compiled  # the underlying re.Pattern

ecma_regex.compile("^a+$").search("aaa\n")  # False  (re says True)
ecma_regex.compile("f.o").search("f\ro")  # False  (re says True)
ecma_regex.compile(r"\d").search("٣")  # False  (re says True)
ecma_regex.compile("^b$", flags="m").search("a\u2028b")  # True

search has RegExp.prototype.test semantics: unanchored, boolean.

Lower-level entry points, if you want the pieces:

tree = ecma_regex.parse(r"(?<year>\d{4})-\d{2}")  # an AST
source = ecma_regex.translate(tree)  # a backend pattern string
flags = ecma_regex.translate_flags(tree)  # re.IGNORECASE, or 0
depth = ecma_regex.star_height(tree)  # ReDoS screening

star_height reports the nesting depth of unbounded quantifiers — a+ is 1, (a+)+ is 2 — which is the classic necessary condition for catastrophic backtracking. It over-reports; it is a screen, not a proof.

Nothing is cached at the compile level. Put your own cache in front of it if you compile the same pattern repeatedly.

Scope

The dialect is ECMA-262 §22.2 with the u flag: the Unicode-mode pattern grammar. Annex B's web-compatibility leniencies (legacy octal escapes, quantifiable assertions, a bare { as a literal, identity escapes of arbitrary characters) are early errors under u, and they are errors here too. a{,3}, a** and (?=a)* all raise.

Everything the grammar allows is parsed: lookbehind, backreferences, named groups and \k<name>, \uXXXX (surrogate pairs combined), \u{...}, \xHH, \cX, \0, \t\n\v\f\r, and \p{...} / \P{...}.

Invalid patterns raise EcmaRegexSyntaxError; valid-but-untranslatable ones raise UnsupportedPatternError. Both subclass EcmaRegexError and carry a position.

Divergence table

What the translation fixes — each row is a silent change of verdict if the pattern goes to re unchanged.

Residual divergences

These cannot be closed inside a backend pattern, so they are documented rather than fixed.

Properties that are derivable everywhere: every General_Category value (including \p{L}, \p{Letter}, \p{General_Category=Nd}) plus ASCII, ASCII_Hex_Digit, Any, Assigned, Bidi_Control, Bidi_Mirrored, Hex_Digit, Join_Control, Lowercase, Noncharacter_Code_Point, Regional_Indicator, Uppercase, White_Space, XID_Continue, XID_Start.

Backends

ecma_regex.compile(r"\p{Script=Greek}+", backend="regex")

Neither backend is linear-time; both backtrack. Use star_height to screen untrusted patterns.

Cost

The first \p{...} translated on the re backend scans every code point to build its range list — about 40 ms on CPython 3.12. The result is cached process-wide, so later uses are dict hits, and every later General_Category property reuses the same scan.

License

MIT.