Debian Codegraph @

docs/whats_new_in_3_3.rst

raw
1 =============================
2 What's New in Pyparsing 3.3.x
3 =============================
4
5 :author: Paul McGuire
6
7 :date: December, 2025
8
9 :abstract: This document summarizes the changes made
10 in the 3.3.x releases of pyparsing.
11
12 .. contents:: :depth: 4
13
14
15 Supported Python versions
16 =========================
17
18 - Python 3.9 or later is required.
19
20 - All unit tests pass with Python 3.14, including the free-threaded build ("3.14t").
21 Note: this does not imply that pyparsing is thread-safe; the tests simply
22 validate that the library runs without errors under the free-threaded
23 interpreter. The test suite does not exercise parsing across multiple
24 threads.
25
26
27 New Features
28 ============
29
30 - Added AI best-practices guidance for using pyparsing to implement parsers.
31 The guidance is stored in ``pyparsing/ai/best_practices.md`` and can be accessed
32 programmatically via ``pyparsing.show_best_practices()`` or from the command line
33 using ``python -m pyparsing.ai.show_best_practices`` (after installing the
34 ``pyparsing`` package).
35
36 - Added performance benchmarking tools and documentation:
37
38 - ``tests/perf_pyparsing.py`` runs a suite of benchmarks that exercise different
39 parts of the pyparsing library. The script can export results as CSV and append
40 to a consolidated data file for cross-version analysis.
41
42 - Runner scripts ``run_perf_all_tags.bat`` (Windows) and ``run_perf_all_tags.sh``
43 (Ubuntu/bash) execute the benchmarks across multiple Python versions (3.9–3.14)
44 and pyparsing versions (3.1.1 through 3.3.0), aggregating results into
45 ``perf_pyparsing.csv`` at the repo root. See ``tests/README.md`` for usage.
46
47 - Improved exception formatting robustness: added exception handling around
48 ``formatted_message()`` to ensure ``str(exception)`` always returns at least
49 some message content, even if formatting fails.
50
51
52 API Changes
53 ===========
54
55 Planned deprecations and guidance for migration
56 -----------------------------------------------
57
58 - Beginning with 3.3.0, pyparsing emits ``DeprecationWarning`` for many pre-PEP8
59 method names (for example, ``ParserElement.parseString``). The PEP8-compliant
60 names were introduced in 3.0.0 (August 2021); the legacy names remain as aliases
61 but are planned to be removed in pyparsing 4.0 (no earlier than 2026).
62
63 - The warnings raised in pyparsing all inherit from ``PyparsingWarning``, and deprecation
64 warnings are of type ``PyparsingDeprecationWarning``, so these types can be selectively
65 enabled or disabled separately from warnings from other packages in an application.
66 Since these classes inherit from ``UserWarning`` and ``DeprecationWarning``, they can
67 also be handled as those standard types.
68
69 - A utility script was added in 3.2.2 to help migrate code to PEP8-compliant
70 names: ``pyparsing/tools/cvt_pyparsing_pep8_names.py``. Run it on one or more
71 files; use ``-u`` to update files in place. Example::
72
73 python -m pyparsing.tools.cvt_pyparsing_pep8_names -u examples/*.py
74
75 - Specific deprecations with behavior notes:
76
77 - ``indentedBlock``: When converted using the migration utility, a ``UserWarning``
78 is emitted indicating that additional code changes are required. The replacement
79 class ``IndentedBlock`` no longer requires passing an external indent stack, and
80 it adds support for nested indentation levels and grouping.
81
82 - ``locatedExpr``: When converted using the migration utility, a ``UserWarning``
83 is emitted indicating that code changes may be required. The PEP8 replacement
84 ``Located`` removes an extra grouping layer from parsed values. If the original
85 ``locatedExpr`` was given a results name, the grouping is retained so that the
86 results-name nesting remains consistent; in that case, no code changes should be
87 required.
88
89
90 Discontinued Features
91 =====================
92
93 - No removals in 3.3.x; however, pre-PEP8 names are now formally deprecated and
94 scheduled for removal in 4.0.
95
96
97 Fixed Bugs
98 ==========
99
100 - Fixed minor formatting issues in ``pyparsing.testing.with_line_numbers`` discovered
101 while developing the TINY language example.
102
103 - ``DelimitedList`` and ``nested_expr`` now auto-suppress delimiting commas when the
104 delimiter is already a ``Suppress``; this avoids the need for extra wrapping.
105
106
107 New / Enhanced Examples
108 =======================
109
110 - Implemented a TINY language parser and interpreter under ``examples/tiny``. The
111 example demonstrates a recommended structure (parser + AST + engine + run) for
112 building a small interpreter with pyparsing. The ``docs`` subdirectory includes
113 transcripts of the AI session used to create the parser and interpreter.
114
115 - Added railroad diagrams for selected examples.
116
117
118 Acknowledgments
119 ===============
120 Again, thanks to the many contributors who submitted issues, questions, suggestions,
121 and PRs.