pyparsing 3.3.0

Pyparsing 3.3.0

on Python PyPI

=======================================================================================
The version 3.3.0 release will begin emitting DeprecationWarnings for pyparsing methods that have been renamed to PEP8-compliant names (introduced in pyparsing 3.0.0, in August, 2021, with legacy names retained as aliases). In preparation, I added in pyparsing 3.2.2 a utility for finding and replacing the legacy method names with the new names. This utility is located at pyparsing/tools/cvt_pep8_names.py. This script will scan all Python files specified on the command line, and if the -u option is selected, will replace all occurrences of the old method names with the new PEP8-compliant names, updating the files in place.

Here is an example that converts all the files in the pyparsing /examples directory:

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

The new names are compatible with pyparsing versions 3.0.0 and later.

=======================================================================================

• Deprecated indentedBlock, when converted using the cvt_pyparsing_pep8_names utility, will emit UserWarnings that additional code changes will be required. This is because the new IndentedBlock class no longer requires the calling code to supply an indent stack, while adding support for nested indentation levels and grouping.

• Deprecated locatedExpr, when converted using the cvt_pyparsing_pep8_names utility, will emit UserWarnings that additional code changes may be required. The new Located class removes the extra grouping level of the parsed values. (If the original locatedExpr parser was defined with a results name, then the extra grouping is retained, so that the results name nesting works properly; in this case, no code changes would be required.)

• Updated all examples and test cases to use PEP8 names (unless the test case is specifically designed to test behavior of a legacy method). Added railroad diagrams for some examples.

• Added exception handling when calling formatted_message(), so that str(exception) always returns at least something.

• All unit tests pass with Python 3.14, including 3.14t. This does not necessarily mean that pyparsing is now thread-safe, just that when run in the free-threaded interpreter, there were no errors. None of the unit tests try to do any parsing with multiple threads - they test the basic functionality of the library, under various versions of packrat and left-recursive parsing.

• Added AI instructions so that AI agents can be prompted with best practices for generating parsers using pyparsing code. These instructions are in the ai/best_practices.md file, and can be accessed programmatically by calling pyparsing.show_best_practices() or running python -m pyparsing.ai.show_best_practices from the command line, after installing the pyparsing package.

• Implemented a TINY language parser/interpreter using pyparsing, in the examples/tiny directory. This is a little tutorial language that I used to demonstrate how to use pyparsing to build a simple interpreter, following a recommended parser+AST+engine+run structure. The docs sub-directory also includes transcripts of the AI session used to create the parser and the interpreter. The samples sub-directory includes a few sample TINY programs.

• Fixed minor formatting bugs in pyparsing.testing.with_line_numbers, found during development of the TINY language example.

• Added test in DelimitedList and nested_expr which auto-suppress delimiting commas to avoid wrapping in a Suppress if delimiter is already a Suppress.

• Added performance benchmarking tools and documentation:

  • tests/perf_pyparsing.py runs a series of benchmark parsing tests, exercising different aspects of the pyparsing package. For cross-version analysis, this script can export results as CSV and append to a consolidated data file.
  • Runner scripts run_perf_all_tags.bat (Windows) and run_perf_all_tags.sh (Ubuntu/bash) execute the benchmark 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 instructions.

• Used performance benchmarking to identify and revert an inefficient utility method used in transform_string (introduced in pyparsing 3.2.0b2).