arpeggio

library2.0.3pypypi✓ verified 24d ago

Arpeggio is a Python library that provides a Packrat parser interpreter. It allows you to define grammars using Python functions or EBNF-like strings and then parse input text according to those grammars. The current version is 2.0.3, with releases focusing on bug fixes, performance, and modern Python compatibility.

serialization

pip install arpeggio

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ARPEGGIO

arpeggio

serializationpythonv2.0.3

Install

1.6s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.002s · 18.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ParserPython

✓ from arpeggio import ParserPython

Parser

✓ from arpeggio import Parser

PTNodeVisitor

✓ from arpeggio import PTNodeVisitor

visit_parse_tree

✓ from arpeggio import visit_parse_tree

This quickstart demonstrates defining a simple arithmetic grammar, parsing an expression, and then using a `PTNodeVisitor` to traverse and evaluate the resulting parse tree.

from arpeggio import ParserPython, visit_parse_tree from arpeggio import PTNodeVisitor # 1. Define your grammar using Python functions or a string def calculator_grammar(): return r""" calc = number (("+"|"-") number)* ; number = /\d+/ ; """ # 2. Create a parser instance # For grammars defined as strings, use Parser(grammar_string) # For grammars defined as Python functions, use ParserPython(grammar_function) parser = ParserPython(calculator_grammar) # 3. Parse input text input_expr = "10 + 20 - 5" parse_tree = parser.parse(input_expr) # 4. (Optional) Process the parse tree using a visitor class CalculatorVisitor(PTNodeVisitor): def visit_number(self, node): return int(node.value) def visit_calc(self, node): # The parse tree node will contain parsed elements as children res = node[0] # first number for i in range(1, len(node), 2): op = node[i].value num = node[i+1] if op == '+': res += num elif op == '-': res -= num return res result = visit_parse_tree(parse_tree, CalculatorVisitor()) assert result == 25 # print(f"Input: '{input_expr}', Result: {result}")

Debug

Known issues

breakingArpeggio 2.0.0 and later dropped support for Python 2.x and Python 3.x up to 3.5. The lowest supported Python version is now 3.6.

fix

Upgrade your Python environment to 3.6 or newer. If you need older Python support, use Arpeggio < 2.0.0 (e.g., 1.x).

affects: >=2.0.0

gotchaAccessing a non-existent rule name as an attribute on a parse tree node (e.g., `parse_tree.non_existent_rule`) will raise an `AttributeError`.

fix

Always check for the presence of a rule or use iteration/indexing (`node[idx]`) if uncertain about rule names. Refer to the documentation on parse tree structure for correct navigation.

affects: >=1.10.0

gotchaError reporting for `NoMatch` exceptions was enhanced in 2.0.0 with the `eval_attrs` call, providing more detailed information on parse failures. Older versions might have less informative error messages.

fix

When debugging parsing issues, ensure you are on Arpeggio >= 2.0.0 and consult the documentation on error handling to fully leverage the detailed `NoMatch` exception information.

affects: >=2.0.0

gotchaArpeggio offers two primary ways to define grammars: using EBNF-like strings with `Parser` or Python functions with `ParserPython`. Mixing these or choosing the wrong parser can lead to unexpected behavior.

fix

Be consistent with your grammar definition method. Use `Parser(grammar_string)` for string-based grammars and `ParserPython(grammar_function)` for Python-function-based grammars.

affects: all

Errors

Common errors & fixes

RecursionError: maximum recursion depth exceeded while calling a Python object

This error occurs due to left recursion in the grammar, leading to infinite recursion.

fix

Refactor the grammar to eliminate left recursion by restructuring the rules to avoid direct or indirect self-references at the beginning of a rule.

arpeggio.NoMatch: Expected EOF at position (3, 1) => ' A *B '.

This error arises when the parser encounters unexpected input, often due to incorrect ordering in an ordered choice.

fix

Ensure that more specific patterns are placed before more general ones in ordered choices to prevent premature matches.

ModuleNotFoundError: No module named 'arpeggio'

This error indicates that the Arpeggio module is not installed in the Python environment.

fix

Install Arpeggio using pip: `pip install Arpeggio`.

arpeggio.NoMatch: Expected '...' or '...' or '...' at position (line, column) => '...'

This exception is raised when the input string does not match the defined grammar at a specific position, meaning there is a syntax error in the input being parsed.

fix

Correct the input string to conform to the grammar, or adjust the grammar definition to accept the given input. You can catch `arpeggio.NoMatch` to handle syntax errors gracefully in your code.

Unrecognized grammar element '...'

This error often occurs when defining grammars using Python notation, specifically due to the use of non-unicode literals in older Python versions, or incorrectly formed grammar elements.

fix

Ensure all string literals used for grammar definition are Unicode. For Python 2, use `from __future__ import unicode_literals`. For modern Python, verify the grammar element's syntax against Arpeggio's documentation.

Upgrade

Version history

2.0.3latest on PyPI · released Sep 12, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/textX/Arpeggio ↗

packagehttps://pypi.org/project/arpeggio/ ↗

homepagehttps://textx.github.io/Arpeggio ↗