Esprima Python fork

A pure Python JavaScript parser and tokenizer targeting ECMAScript 2026 on Python 3.11+. Modern expressions, classes, modules, Unicode and regex grammar are supported with read-only scope and early-error validation. The 5.0 release series' tested coverage and deliberate limits are described in conformance notes.

pip install esprima-fork

import esprima

tree = esprima.parseScript("const answer = 42", {"range": True, "loc": True})
print(esprima.toDict(tree))

This distribution imports as esprima. Do not install the separate upstream esprima distribution in the same environment: both own that import directory. This fork is based on German M. Bravo's port and Ariya Hidayat's Esprima; upstream author credits and BSD notices are retained.

Upgrading from 4.x

Version 5.0 requires Python 3.11 or newer. Parsing defaults to ECMAScript 2026; select ecmaVersion=2017 when an older grammar is required. Source ranges and columns now use JavaScript UTF-16 units; positionEncoding='scalar' restores Python character offsets. Scope and early-error checks reject invalid programs that older releases sometimes accepted. JSON output retains required null fields and safe BigInt, regex and non-finite Number descriptors. Check consumers of the old AST format against the migration contract. The import name remains esprima; esprima.version is the distribution version string and esprima.__version__ remains the historical (major, minor, patch) tuple. See the changelog for the complete changes.

tree = esprima.parseModule('export const value = obj?.value ?? 123n;',
                          {'range': True, 'loc': True})
mapping = esprima.toDict(tree)

See the AST compatibility contract for the modern node format and UTF-16 position units. Use positionEncoding='scalar' for legacy Python-index behavior, ecmaVersion=2017 for an older grammar, and jsx=True for JSX fragments/elements/spread children. comment=True collects comments; attachComment=True also attaches them for generation. Required null fields and BigInt/regex/overflow-Number descriptors survive JSON serialization.

The CLI accepts UTF-8 files or stdin. JSON goes to stdout; parse diagnostics and optional --timing go to stderr, and errors return a nonzero status.

esprima --module --range example.js
esprima --jsx --tokens example.jsx

Development

python -m unittest discover -v
python -m pytest
python -m build

The legacy corpus contains 1,604 JavaScript fixtures plus two API tests. The discovery guard verifies that every fixture runs once. Install the dev extra in a virtual environment for the additional checks.

Install the coordinated walker/utility/generator candidates to run all pipeline tests. Reference parsers are development-only: npm ci --prefix tools/reference. Frozen Test262 corpora run without a network or a JavaScript runtime; Node is used for independent pipeline/source-map comparisons. Build wheels from source archives and run python tools/check_distribution.py before release. Maintainers can follow the release instructions.

The performance report records paired measurements and their limits. The latest parser pass reduced default parsing time for a separate large bundle by 15.7%, with default garbage collection and full validation retained. Serialization has a smaller improvement; see the report for exact baselines and consumer costs.