Skip to content

Changelog

All notable changes to this project are documented here. The format is based on Keep a Changelog, and from 1.0 the project follows semantic versioning (see the version policy in CONTRIBUTING.md).

[1.0.0] - 2026-07-08

First stable release. Antlrope is a fast, C++-accelerated ANTLR runtime for Python: it drives the official ANTLR4 C++ runtime's ATN interpreter directly from the serialized ATN that the stock -Dlanguage=Python3 ANTLR tool already emits — no per-grammar codegen, nothing to compile — and delivers the parse to Python as one bulk, filtered event stream instead of a per-node tree walk (typically 10–20× the official pure-Python runtime). The public API — FacadeListener and its generated <Grammar>EventListener facades, walk / walk_parallel, the chunking and streaming family, and the antlrope command group — is stable as of this release.

Final pre-release polish (over the 0.x history below):

Changed

  • The CLI prints a clean one-line error (exit status 2) for bad input — an unimportable module, a module that is not a generated parser, an unreadable or unwritable file — instead of a Python traceback.
  • FacadeListener.rule_name now raises IndexError for any out-of-range rule index; previously a negative index silently wrapped from the end.

Added

  • Release engineering: complete PyPI metadata (development-status classifier, documentation/changelog/issue URLs), a documented release procedure (RELEASING.md), automated versioned-docs deployment on release tags, and a Windows CI job running the full test suite (Windows wheels were previously only import-smoke-tested).

0.x development history

The 0.x versions (0.1.0 2026-05-31 through 0.2.28 2026-06-28) were development builds, never published to PyPI. Condensed highlights, roughly in order:

  • Engine (0.1.0): the bulk filtered event stream over a vendored ANTLR4 C++ runtime — parse in C++, cross into Python once with (kind, payload, start, stop) int32 records, filter unsubscribed rules/tokens natively; GIL released during the parse; py.typed + a checked-in _native stub. Two runtime patches written for upstream: lock-free DFA-edge reads and per-DFA write locks (shared specs scale across threads instead of running slower than serial). A heap-buffer-overflow in the patched DFA-edge cache was found and fixed under AddressSanitizer, which the CI now runs routinely.
  • Facade: generated <Grammar>EventListener classes with per-rule callbacks, token-type constants (symbolic plus ANTLR's positional T__n literal names), and baked-in lexer/parser — listener.walk(text) needs no class arguments. walk_parallel parses chunks across cores as a lazy, order-preserving iterator. Consumer helpers grew in: depth / rule_stack / current_rule, text, token_name / rule_name, line_col / span / sourcename, collected syntax_errors (now ParseError exceptions), and the enterEveryRule / exitEveryRule hooks.
  • Chunking family: token-aware split_on_token / split_between_tokens over a C++ lex pass; regex split_on_pattern / chunk_by_pattern; structural chunk_by_rule; and bounded-memory streaming counterparts stream_on_token, stream_on_pattern, and stream_by_rule (which fails loudly on malformed record sequences). All yield positioned Chunks with optional sourcename; trim=False preserves whitespace terminators.
  • API consolidation: the chunkers and spec handling moved onto FacadeListener; the low-level layer (event buffers, native specs, typing protocols, the cached= option) went private, leaving a seven-name public surface plus a clear_cache() escape hatch.
  • CLI: grew from a single generator command into the antlrope command group — gen (with a deterministic origin header), regen and up-to-date (regenerate / staleness-check from that header), check (flag semantic predicates and embedded actions the ATN interpreter cannot run), and rules / tokens introspection.
  • Packaging: renamed from antlr-pyfacade to antlrope (0.2.0); Python floor raised to 3.12 so a single Stable-ABI (cp312-abi3) wheel per platform covers 3.12+ (Linux x86_64/aarch64, macOS x86_64/arm64, Windows amd64).
  • Docs: the zensical + mkdocstrings site (user guide, examples, glossary, generated API and CLI references), an LLM-oriented llms.txt, and the SystemRDL benchmark: ~21× the pure-Python runtime and ~8× the speedy-antlr accelerator end-to-end on a 2.6 MB input, at lower peak memory.