¶

Parse text fast from Python using 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, not 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 like enterFunction / visitTerminal. The parsing itself runs in the official ANTLR4 C++ runtime and the results stream into your callbacks in a single batch — 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 → — install to 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 lexer/parser are baked into the facade

Override only the callbacks you care about; everything you don't ask for is skipped before it ever reaches Python.

Will it work with my grammar?¶

Usually yes. Grammars that describe structure — data formats, config languages, query languages, most DSLs and programming languages — work out of the box.

It won't work if your grammar depends on 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 the details and how to tell — or just ask: antlrope check <parser-module> scans a generated parser and reports every predicate and action by rule.

Where to go next¶

• Installation — pip/conda install, supported Pythons/platforms, and the ANTLR tool you need to generate parsers.
• Getting started — the full generate → write a listener → run walkthrough. Start here.
• Chunking and Parallel parsing — split large or many-record input and parse the pieces across cores.
• Migrating from antlr4-python3-runtime — if you already use the official runtime's ParseTreeListener, this maps it onto the Antlrope facade.
• API reference — every callback, option, and helper.
• How it works — optional background on why it's fast.
• Performance & limitations — the speed ceiling and the predicate/action boundary, in full.

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 the file), your grammar, and, when porting, your existing listener. It covers the event model, the callback shapes, and the porting mapping.