# 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.