Version 3.2.0 - October, 2024

• Discontinued support for Python 3.6, 3.7, and 3.8. Adopted new Python features from Python versions 3.7-3.9:

  • Updated type annotations to use built-in container types instead of names imported from thetyping module (e.g.,list[str] vsList[str]).
  • Reworked portions of the packrat cache to leverage insertion-preserving ordering in dicts (including removal of uses ofOrderedDict).
  • Changedpdb.set_trace() call inParserElement.set_break() tobreakpoint().
  • Convertedtyping.NamedTuple todataclasses.dataclass in railroad diagramming code.
  • Addedfrom __future__ import annotations to clean up some type annotations. (with assistance from ISyncWithFoo, issueChanges towards 3.2.0 #535, thanks for the help!)

• POSSIBLE BREAKING CHANGES

  The following bugfixes may result in subtle changes in the results returned or exceptions raised by pyparsing.

  • Fixed code inParseElementEnhance subclasses that replaced detailed exception messages raised in contained expressions with a less-specific and less-informative generic exception message and location.

    If your code has conditional logic based on the message content in raisedParseExceptions, this bugfix may require changes in your code.

  • Fixed bug intransform_string() where whitespace in the input string was not properly preserved in the output string.

    If your code usestransform_string, this bugfix may require changes in your code.

  • Fixed bug where anIndexError raised in a parse action was incorrectly handled as anIndexError raised as part of theParserElement parsing methods, and reraised as aParseException. Now anIndexError that raises inside a parse action will properly propagate out as anIndexError. (IssueIndexErrors are handled differently than other exceptions #573, reported by August Karlstedt, thanks!)

    If your code raisesIndexErrors in parse actions, this bugfix may require changes in your code.

• FIXES AND NEW FEATURES

  • Added type annotations to remainder ofpyparsing package, and addedmypy run totox.ini, so that type annotations are now run as part of pyparsing's CI. Addresses IssueType checking as part of the CI pipeline #373, raised by Iwan Aucamp, thanks!

  • Exception message format can now be customized, by overridingParseBaseException.format_message:

    def custom_exception_message(exc) -> str:    found_phrase = f", found {exc.found}" if exc.found else ""    return f"{exc.lineno}:{exc.column} {exc.msg}{found_phrase}"ParseBaseException.formatted_message = custom_exception_message

    (PRAdd found string as property #571 submitted by Odysseyas Krystalakos, nice work!)

  • run_tests now detects if an exception is raised in a parse action, and will report it with an enhanced error message, with the exception type, string, and parse action name.

  • QuotedString now handles translation of escaped integer, hex, octal, and Unicode sequences to their corresponding characters.

  • Fixed the displayed output ofRegex terms to deduplicate repeated backslashes, for easier reading in debugging, printing, and railroad diagrams.

  • Fixed (or at least reduced) elusive bug when generating railroad diagrams, where some diagram elements were just empty blocks. Fix submitted by RoDuth, thanks a ton!

  • Fixed railroad diagrams that get generated with a parser containing a Regex element defined using a verbose pattern - the pattern gets flattened and comments removed before creating the corresponding diagram element.

  • Defined a more performant regular expression used internally bycommon_html_entity.

  • Regex instances can now be created using a callable that takes no arguments and just returns a string or a compiled regular expression, so that creating complex regular expression patterns can be deferred until they are actually used for the first time in the parser.

  • Added optionalflatten Boolean argument toParseResults.as_list(), to return the parsed values in a flattened list.

  • Addedindent andbase_1 arguments topyparsing.testing.with_line_numbers. When usingwith_line_numbers inside a parse action, setbase_1=False, since the reportedloc value is 0-based.indent can be a leading string (typically of spaces or tabs) to indent the numbered string passed towith_line_numbers. Added while working onset_parse_action handler receives seemingly erroneous loc argument #557, reported by Bernd Wechner.

• NEW/ENHANCED EXAMPLES

  • Added query syntax tomongodb_query_expression.py with:

    • better support for array fields ("contains", "contains all", "contains any", and "contains none")
    • "like" and "not like" operators to support SQL "%" wildcard matching and "=~" operator to support regex matching
    • text search using "search for"
    • dates and datetimes as query values
    • a[0] style array referencing

  • Addedlox_parser.py example, a parser for the Lox language used as a tutorial in Robert Nystrom's "Crafting Interpreters" (http://craftinginterpreters.com/). With helpful corrections from RoDuth.

  • Addedcomplex_chemical_formulas.py example, to add parsing capability for formulas such as "3(C₆H₅OH)₂".

  • Updatedtag_emitter.py to use newTag class, introduced in pyparsing 3.1.3.