¶

Parse text quickly from Python with an ANTLR grammar, without writing or compiling any C or C++ yourself.

antlrope = ANTLR + Ordered Parse Events: the parse is handed to you as one ordered stream of events instead of a per-node parse-tree walk.

Bring an ANTLR grammar (.g4), generate a parser with the ordinary ANTLR tool, install antlrope, generate a small facade from that parser, and write a plain Python class with named callbacks such as enterFunction and visitTerminal. Parsing runs in the official ANTLR4 C++ runtime, and the results reach your callbacks in a single batch. This is typically 10–20× faster than the official pure-Python runtime, and faster still when you subscribe to only part of the grammar.

You do not need to understand the internals to use it. If you can write an ANTLR grammar and a Python class, you have everything you need.

Get started →: go from installation to a first result in a few minutes.

What you write¶

from my_listener import MyGrammarEventListener      # generated by antlrope

class Collector(MyGrammarEventListener):
    def enterPair(self) -> None:        # one callback per grammar rule
        ...
    def visitTerminal(self, token_type: int, text: str) -> None:
        ...

c = Collector()
c.walk(source_text)        # the facade already knows its lexer and parser

Override only the callbacks you care about. Events you don't subscribe to are dropped before they reach Python.

Will it work with my grammar?¶

Usually, yes. Grammars that describe structure, such as data formats, configuration languages, query languages, and most DSLs and programming languages, work without changes.

It won't work if your grammar needs semantic predicates ({...}?) or embedded actions ({...} code blocks) to parse correctly. Those are target-language code snippets that this runtime does not execute. If your grammar needs them, use the official antlr4-python3-runtime instead. See Performance & limitations for details and how to tell whether your grammar is affected. You can also run antlrope check <parser-module>, which scans a generated parser and reports every predicate and action by rule.

Where to go next¶

• Installation: installing with pip or conda, supported Python versions and platforms, and the ANTLR tool you need to generate parsers.
• Getting started: a complete walkthrough from generating a parser to writing and running a listener. Start here.
• Chunking and Parallel parsing: split large inputs, or inputs made of many records, and parse the pieces on multiple cores.
• Migrating from antlr4-python3-runtime: if you already use the official runtime's ParseTreeListener, this page shows the facade equivalent of each part.
• API reference: every callback, option, and helper.
• How it works: optional background on why it is fast.
• Performance & limitations: the limits on speed, and which grammars (those with predicates or actions) are not supported.

Using an AI coding assistant¶

These docs are summarized for LLMs at llms.txt (see llmstxt.org). To have an AI assistant write a listener or port an existing ParseTreeListener, give it that URL (or paste in the file), your grammar, and, if you are porting, your existing listener. It covers the event model, the callback shapes, and the porting mapping.