Metadata-Version: 2.5
Name: esprima-fork
Version: 5.0.0
Summary: Pure Python ECMAScript 2026 parser and tokenizer with ESTree output
Project-URL: Homepage, https://github.com/0o120/esprima-python
Project-URL: Source, https://github.com/0o120/esprima-python
Project-URL: Issues, https://github.com/0o120/esprima-python/issues
Project-URL: Documentation, https://github.com/0o120/esprima-python/blob/master/README.md
Project-URL: Changelog, https://github.com/0o120/esprima-python/blob/master/CHANGELOG.md
Project-URL: PyPI, https://pypi.org/project/esprima-fork/
Project-URL: Upstream, https://github.com/Kronuz/esprima-python
Author-email: "German M. Bravo (Kronuz)" <german.mb@gmail.com>
Maintainer-email: 0x78 <contact@0x78.com>
License-Expression: BSD-2-Clause AND Unicode-3.0
License-File: LICENSE
License-File: LICENSE.BSD
License-File: data/unicode/LICENSE.txt
Keywords: ast,ecmascript,esprima,javascript,parser
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling<2,>=1.32.4; extra == 'dev'
Requires-Dist: hypothesis>=6.120; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/0o120/esprima-python/blob/master/docs/CONFORMANCE.md).

```sh
pip install esprima-fork
```

```python
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](https://github.com/0o120/esprima-python/blob/master/docs/AST_COMPATIBILITY.md).
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](https://github.com/0o120/esprima-python/blob/master/CHANGELOG.md)
for the complete changes.

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

See [the AST compatibility contract](https://github.com/0o120/esprima-python/blob/master/docs/AST_COMPATIBILITY.md) 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.

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

## Development

```sh
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](https://github.com/0o120/esprima-python/blob/master/RELEASING.md).

The [performance report](https://github.com/0o120/esprima-python/blob/master/docs/PERFORMANCE.md)
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.
