Coming from Lark

hyperlark is a drop-in replacement for the Python lark library on the LALR + Earley surface. If you already use lark, most code works by changing one import.

Migrating

import hyperlark as lark   # was: import lark

Lark, Tree, Token, the Transformer / Visitor / Interpreter / v_args toolkit, and the lark.exceptions.* hierarchy all match — same names, attributes, and message shapes. There is no runtime lark dependency; the grammar compiler is native.

The compatibility is tested — with Lark’s own tests

hyperlark’s Python test suite runs lark’s actual test suite against it (pinned to a specific lark commit): 845 of lark’s own tests pass, and the rest are documented skips for deferred features. This is the strongest drop-in proof there is — not a re-implementation of the tests, but lark’s real assertions running against hyperlark. The suite runs with fast_tokens=False (lark-identical str-subclass tokens — see below); hyperlark’s own default is the faster FastToken.

What differs

A handful of deliberate, documented differences (the full list, in detail, is in Divergences from Lark):

• FastToken default. Token leaves everywhere — on parse trees, from lex(), and in embedded-transformer= callbacks — are fast FastToken objects by default. They compare by value (tok == "x"), expose the full Token surface (.type, .value, positions), and satisfy isinstance(tok, Token), but they are not str subclasses: str-bound code ("".join(children), re.match(p, tok), isinstance(tok, str)) needs fast_tokens=False, which restores lark-identical str-subclass tokens everywhere. The lark-suite parity run above uses that mode.
• Deferred features raise or are absent: the reconstructor, tree-templates, the standalone tool, and TextSlice inputs. An option hyperlark recognizes but doesn’t implement raises a clear ConfigurationError rather than silently doing nothing — see the table of those options. (cache= itself works, Lark-style.)
• CYK is not implemented (a sanctioned drop).

Full object identity (mixed imports)

If you import both lark and hyperlark and need real lark.Token / lark.exceptions.* class identity (isinstance(x, lark.Token)), install the compat extra and use the hyperlark.compat module:

pip install hyperlark[compat]

Most projects don’t need this. Compat mode is incomplete in this beta and its gaps are silent — see Class identity, and compat mode.