What’s New in Pyparsing 3.3.x

author:

Paul McGuire

date:

December, 2025

abstract:

This document summarizes the changes made in the 3.3.x releases of pyparsing.

Supported Python versions

  • Python 3.9 or later is required.

  • All unit tests pass with Python 3.14, including the free-threaded build (“3.14t”). Note: this does not imply that pyparsing is thread-safe; the tests simply validate that the library runs without errors under the free-threaded interpreter. The test suite does not exercise parsing across multiple threads.

New Features

  • Added AI best-practices guidance for using pyparsing to implement parsers. The guidance is stored in pyparsing/ai/best_practices.md and can be accessed programmatically via pyparsing.show_best_practices() or from the command line using python -m pyparsing.ai.show_best_practices (after installing the pyparsing package).

  • Added performance benchmarking tools and documentation:

    • tests/perf_pyparsing.py runs a suite of benchmarks that exercise different parts of the pyparsing library. The script can export results as CSV and append to a consolidated data file for cross-version analysis.

    • Runner scripts run_perf_all_tags.bat (Windows) and run_perf_all_tags.sh (Ubuntu/bash) execute the benchmarks across multiple Python versions (3.9–3.14) and pyparsing versions (3.1.1 through 3.3.0), aggregating results into perf_pyparsing.csv at the repo root. See tests/README.md for usage.

  • Improved exception formatting robustness: added exception handling around formatted_message() to ensure str(exception) always returns at least some message content, even if formatting fails.

API Changes

Planned deprecations and guidance for migration

  • Beginning with 3.3.0, pyparsing emits DeprecationWarning for many pre-PEP8 method names (for example, ParserElement.parseString). The PEP8-compliant names were introduced in 3.0.0 (August 2021); the legacy names remain as aliases but are planned to be removed in pyparsing 4.0 (no earlier than 2026).

  • The warnings raised in pyparsing all inherit from PyparsingWarning, and deprecation warnings are of type PyparsingDeprecationWarning, so these types can be selectively enabled or disabled separately from warnings from other packages in an application. Since these classes inherit from UserWarning and DeprecationWarning, they can also be handled as those standard types.

  • A utility script was added in 3.2.2 to help migrate code to PEP8-compliant names: pyparsing/tools/cvt_pyparsing_pep8_names.py. Run it on one or more files; use -u to update files in place. Example:

    python -m pyparsing.tools.cvt_pyparsing_pep8_names -u examples/*.py

  • Specific deprecations with behavior notes:

    • indentedBlock: When converted using the migration utility, a UserWarning is emitted indicating that additional code changes are required. The replacement class IndentedBlock no longer requires passing an external indent stack, and it adds support for nested indentation levels and grouping.

    • locatedExpr: When converted using the migration utility, a UserWarning is emitted indicating that code changes may be required. The PEP8 replacement Located removes an extra grouping layer from parsed values. If the original locatedExpr was given a results name, the grouping is retained so that the results-name nesting remains consistent; in that case, no code changes should be required.

Discontinued Features

  • No removals in 3.3.x; however, pre-PEP8 names are now formally deprecated and scheduled for removal in 4.0.

Fixed Bugs

  • Fixed minor formatting issues in pyparsing.testing.with_line_numbers discovered while developing the TINY language example.

  • DelimitedList and nested_expr now auto-suppress delimiting commas when the delimiter is already a Suppress; this avoids the need for extra wrapping.

New / Enhanced Examples

  • Implemented a TINY language parser and interpreter under examples/tiny. The example demonstrates a recommended structure (parser + AST + engine + run) for building a small interpreter with pyparsing. The docs subdirectory includes transcripts of the AI session used to create the parser and interpreter.

  • Added railroad diagrams for selected examples.

Acknowledgments

Again, thanks to the many contributors who submitted issues, questions, suggestions, and PRs.