antlrope

CI coverage PyPI conda-forge Python docs

A fast, C++-accelerated ANTLR runtime for Python for target-agnostic grammars

antlrope = ANTLR + Ordered Parse Events — your parse delivered as one ordered stream of events, not a per-node tree walk.

10–20× faster than the official pure-Python antlr4-python3-runtime on workloads that touch most nodes — and more when your listener subscribes to only a subset of the grammar.

Parsing and reading a 2.6 MB SystemRDL file: antlrope is ~21x faster than the pure-Python runtime and ~8x faster than the speedy-antlr accelerator, at lower peak memory

Parsing + reading a real 2.6 MB SystemRDL file — see the full benchmark (vs the pure-Python runtime and the speedy-antlr accelerator).

Generate your parser with the ordinary ANTLR tool targeting Python, install this package, generate a small facade class, and write a pure-Python event listener. Parsing itself runs inside the official ANTLR4 C++ runtime, driven directly from the serialized ATN (Augmented Transition Network) the stock Python target already emits. Instead of a per-node parse-tree walk (one foreign-function crossing per tree node), the C++ side collects a single bulk, filtered event stream and hands it to Python in one transfer — and it drops the rules/tokens your listener doesn't subscribe to before they ever reach Python.

It complements, rather than replaces, the official antlr4-python3-runtime: same generated parser, a faster way to consume it.

Install

From PyPI:

pip install antlrope

Or from conda-forge (with conda, mamba, or pixi):

conda install -c conda-forge antlrope

Either way you get a pre-compiled binary — nothing to build — and the official antlr4-python3-runtime is pulled in automatically.

Quickstart

  1. Generate your parser with the stock ANTLR tool (Python target):

    antlr4 -Dlanguage=Python3 MyGrammar.g4 -o generated

  2. Generate the facade from the generated parser module:

    antlrope gen generated.MyGrammarParser MyGrammar -o my_listener.py

    This emits a MyGrammarEventListener base class with enter<Rule> / exit<Rule> / visitTerminal / visitError stubs and token-type constants. The facade also imports and bakes in your lexer/parser, so you never pass them at parse time. The lexer module is derived from the parser's by ANTLR's <Grammar>Lexer / <Grammar>Parser convention; pass --lexer if yours is named differently.

  3. Subclass it and override only the callbacks you care about:

    from my_listener import MyGrammarEventListener

class Collector(MyGrammarEventListener):
    def enterPair(self) -> None:
        ...
    def visitTerminal(self, token_type: int, text: str) -> None:
        ...

Collector().walk(source_text)

Only the callbacks you override drive native masks, so the C++ side skips every other rule/token — the fewer node kinds you subscribe to, the faster the walk.

How it works

  • The C++ extension deserializes the ATN from your generated lexer/parser and drives LexerInterpreter / ParserInterpreter — no generated C++ parser.
  • A native iterative depth-first traversal over the finished parse tree appends fixed (kind, payload, start, stop) int32 records to one buffer (parse_events).
  • kind: 0=ENTER_RULE, 1=EXIT_RULE, 2=TERMINAL, 3=ERROR; payload is the rule index or token type; start/stop are char indices into the source (-1 for rule events). Token text is recovered Python-side by slicing text[start:stop + 1] — no string copies cross the boundary.
  • Rule/token masks built from your overrides filter the stream in C++.

Limitations

This can only be used for target-language-agnostic grammars. This runtime executes the interpreted ATN; it cannot run target-language semantic predicates or embedded grammar actions. Grammars that depend on them will not parse correctly here. See docs/ for the full discussion and the performance characteristics of the bulk event-stream approach.

Contributing

Development setup, pixi environments, and the vendored-runtime workflow live in CONTRIBUTING.md.

Documentation

Full documentation: zuzukin.github.io/antlrope. In the repo, see docs/: getting started, installation, API reference, chunking, migrating from antlr4-python3-runtime, performance & limitations, how it works, and the SystemRDL benchmark.

Using an AI coding assistant to write a listener (or port a ParseTreeListener)? Give it the LLM-oriented docs summary at zuzukin.github.io/antlrope/llms.txt plus your grammar — and, when porting, your existing listener.

License

Apache-2.0. Bundles the ANTLR4 C++ runtime (BSD-3-Clause) under vendor/antlr4-cpp/; see vendor/antlr4-cpp/UPDATING.md for provenance.

Project links

Data verified by PyPI on Jul 25, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for analog-cbarber from gravatar.com analog-cbarber

Credits

Author: Christopher Barber

GitHub Statistics

Data verified by PyPI on Jul 25, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache License)

Requires

Python >=3.12

Tags

antlr antlr4 parser parsing grammar python

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

antlrope-1.0.1.tar.gz (443.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

antlrope-1.0.1-cp312-abi3-win_amd64.whl (286.9 kB view details)

Uploaded CPython 3.12+Windows x86-64

antlrope-1.0.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (436.9 kB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ x86-64

antlrope-1.0.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (421.0 kB view details)

Uploaded CPython 3.12+manylinux: glibc 2.17+ ARM64

antlrope-1.0.1-cp312-abi3-macosx_11_0_x86_64.whl (369.8 kB view details)

Uploaded CPython 3.12+macOS 11.0+ x86-64

antlrope-1.0.1-cp312-abi3-macosx_11_0_arm64.whl (359.0 kB view details)

Uploaded CPython 3.12+macOS 11.0+ ARM64

File details

Details for the file antlrope-1.0.1.tar.gz.

File metadata

  • Download URL: antlrope-1.0.1.tar.gz
  • Upload date:
  • Size: 443.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for antlrope-1.0.1.tar.gz
Algorithm Hash digest
SHA256 678b235a7ed094074fa0c28133ee99d0570c44954307a474c5ed8d5fc377ecaa
MD5 0fc5545b8ed8330e2ca5608b58a792b1
BLAKE2b-256 15665737d989502a699753bbed774b862a732a53bf0e5641fe71a31c6e370c79

See more details on using hashes here.

Provenance

The following attestation bundles were made for antlrope-1.0.1.tar.gz:

Publisher: wheels.yml on zuzukin/antlrope

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file antlrope-1.0.1-cp312-abi3-win_amd64.whl.

File metadata

  • Download URL: antlrope-1.0.1-cp312-abi3-win_amd64.whl
  • Upload date:
  • Size: 286.9 kB
  • Tags: CPython 3.12+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for antlrope-1.0.1-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 ea3fc23e0bfb281030b6bd741c1bcd022d60eae0488a3aae5e1281d0ed324cb0
MD5 0f9853fcdafc22aa39706eb823b80f4b
BLAKE2b-256 c3e78a008d529160802965b0434228fd63f8329459edfa256cc95084d84d7b93

See more details on using hashes here.

Provenance

The following attestation bundles were made for antlrope-1.0.1-cp312-abi3-win_amd64.whl:

Publisher: wheels.yml on zuzukin/antlrope

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file antlrope-1.0.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for antlrope-1.0.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f358f1c88c2c39671ce40c23f2a3968c1688461cf3ef9f9d3f23d1f8f353aec2
MD5 1fc8f79b6e42c2697d21855af60ffe85
BLAKE2b-256 50e0aaa9b0c14d96aff8b230b1874a9a66a88086ee92154de74c084c6ba1b131

See more details on using hashes here.

Provenance

The following attestation bundles were made for antlrope-1.0.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on zuzukin/antlrope

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file antlrope-1.0.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for antlrope-1.0.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 28bab39e47d55b8b5c356e4b8549524f9461c74053f116fa51d2edd0f387b252
MD5 2281a798b921985e560501aafa22f03d
BLAKE2b-256 28bf119b083c171e5145d2ca743d505a9fbf0671e976ff82665c961217c7dc8f

See more details on using hashes here.

Provenance

The following attestation bundles were made for antlrope-1.0.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: wheels.yml on zuzukin/antlrope

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file antlrope-1.0.1-cp312-abi3-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for antlrope-1.0.1-cp312-abi3-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 d7301bdf483d71ab7f4e04dd22634eddea275491ab9c26e8277423d494b3530b
MD5 30012b3a3e03bcd69f4eed0d50e120fe
BLAKE2b-256 82b680d892ea482abcf240960412c4b39bafc384887289f6e6422d08a32b28c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for antlrope-1.0.1-cp312-abi3-macosx_11_0_x86_64.whl:

Publisher: wheels.yml on zuzukin/antlrope

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file antlrope-1.0.1-cp312-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for antlrope-1.0.1-cp312-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b4abd901c12e687003e0e364e2335b1bd46a751124ca718a8dc944d0e6aaebfb
MD5 408a987bbf0dee39b0a69195bdc7e434
BLAKE2b-256 ff2885b9f6582adb257cca10bab484d8aae39f5b3fb6ce732b1cfe6a4d5bf86b

See more details on using hashes here.

Provenance

The following attestation bundles were made for antlrope-1.0.1-cp312-abi3-macosx_11_0_arm64.whl:

Publisher: wheels.yml on zuzukin/antlrope

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.1 This release

6 files

1.0.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page