@ai-ecoverse/py-pyparsing 3.3.3-1

package/lib/python3.14/site-packages/pyparsing/actions.py

@@ -0,0 +1,264 @@
+# actions.py
+from __future__ import annotations
+
+from typing import Union, Callable, Any
+
+from .exceptions import ParseException
+from .util import col, replaced_by_pep8
+from .results import ParseResults
+
+
+ParseAction = Union[
+    Callable[[], Any],
+    Callable[[ParseResults], Any],
+    Callable[[int, ParseResults], Any],
+    Callable[[str, int, ParseResults], Any],
+]
+
+
+class OnlyOnce:
+    """
+    Wrapper for parse actions, to ensure they are only called once.
+    Note: parse action signature must include all 3 arguments.
+    """
+
+    def __init__(self, method_call: Callable[[str, int, ParseResults], Any]) -> None:
+        from .core import _trim_arity
+
+        self.callable = _trim_arity(method_call)
+        self.called = False
+
+    def __call__(self, s: str, l: int, t: ParseResults) -> ParseResults:
+        if not self.called:
+            results = self.callable(s, l, t)
+            self.called = True
+            return results
+        raise ParseException(s, l, "OnlyOnce obj called multiple times w/out reset")
+
+    def reset(self):
+        """
+        Allow the associated parse action to be called once more.
+        """
+
+        self.called = False
+
+
+def match_only_at_col(n: int) -> ParseAction:
+    """
+    Helper method for defining parse actions that require matching at
+    a specific column in the input text.
+    """
+
+    def verify_col(strg: str, locn: int, toks: ParseResults) -> None:
+        if col(locn, strg) != n:
+            raise ParseException(strg, locn, f"matched token not at column {n}")
+
+    return verify_col
+
+
+def replace_with(repl_str: Any) -> ParseAction:
+    """
+    Helper method for common parse actions that simply return
+    a literal value.  Especially useful when used with
+    :meth:`~ParserElement.transform_string`.
+
+    Example:
+
+    .. doctest::
+
+       >>> num = Word(nums).set_parse_action(lambda toks: int(toks[0]))
+       >>> na = one_of("N/A NA").set_parse_action(replace_with(math.nan))
+       >>> term = na | num
+
+       >>> term[1, ...].parse_string("324 234 N/A 234")
+       ParseResults([324, 234, nan, 234], {})
+    """
+    return lambda s, l, t: [repl_str]
+
+
+def remove_quotes(s: str, l: int, t: ParseResults) -> Any:
+    r"""
+    Helper parse action for removing quotation marks from parsed
+    quoted strings, that use a single character for quoting. For parsing
+    strings that may have multiple characters, use the :class:`QuotedString`
+    class.
+
+    Example:
+
+    .. doctest::
+
+       >>> # by default, quotation marks are included in parsed results
+       >>> quoted_string.parse_string("'Now is the Winter of our Discontent'")
+       ParseResults(["'Now is the Winter of our Discontent'"], {})
+
+       >>> # use remove_quotes to strip quotation marks from parsed results
+       >>> dequoted = quoted_string().set_parse_action(remove_quotes)
+       >>> dequoted.parse_string("'Now is the Winter of our Discontent'")
+       ParseResults(['Now is the Winter of our Discontent'], {})
+    """
+    return t[0][1:-1]
+
+
+def with_attribute(*args: tuple[str, str], **attr_dict) -> ParseAction:
+    """
+    Helper to create a validating parse action to be used with start
+    tags created with :class:`make_xml_tags` or
+    :class:`make_html_tags`. Use ``with_attribute`` to qualify
+    a starting tag with a required attribute value, to avoid false
+    matches on common tags such as ``<TD>`` or ``<DIV>``.
+
+    Call ``with_attribute`` with a series of attribute names and
+    values. Specify the list of filter attributes names and values as:
+
+    - keyword arguments, as in ``(align="right")``, or
+    - as an explicit dict with ``**`` operator, when an attribute
+      name is also a Python reserved word, as in ``**{"class":"Customer", "align":"right"}``
+    - a list of name-value tuples, as in ``(("ns1:class", "Customer"), ("ns2:align", "right"))``
+
+    For attribute names with a namespace prefix, you must use the second
+    form.  Attribute names are matched insensitive to upper/lower case.
+
+    If just testing for ``class`` (with or without a namespace), use
+    :class:`with_class`.
+
+    To verify that the attribute exists, but without specifying a value,
+    pass ``with_attribute.ANY_VALUE`` as the value.
+
+    The next two examples use the following input data and tag parsers:
+
+    .. testcode::
+
+       html = '''
+           <div>
+           Some text
+           <div type="grid">1 4 0 1 0</div>
+           <div type="graph">1,3 2,3 1,1</div>
+           <div>this has no type</div>
+           </div>
+       '''
+       div,div_end = make_html_tags("div")
+
+    Only match div tag having a type attribute with value "grid":
+
+    .. testcode::
+
+       div_grid = div().set_parse_action(with_attribute(type="grid"))
+       grid_expr = div_grid + SkipTo(div | div_end)("body")
+       for grid_header in grid_expr.search_string(html):
+           print(grid_header.body)
+
+    prints:
+
+    .. testoutput::
+
+       1 4 0 1 0
+
+    Construct a match with any div tag having a type attribute,
+    regardless of the value:
+
+    .. testcode::
+
+       div_any_type = div().set_parse_action(
+           with_attribute(type=with_attribute.ANY_VALUE)
+       )
+       div_expr = div_any_type + SkipTo(div | div_end)("body")
+       for div_header in div_expr.search_string(html):
+           print(div_header.body)
+
+    prints:
+
+    .. testoutput::
+
+       1 4 0 1 0
+       1,3 2,3 1,1
+    """
+    attrs_list: list[tuple[str, str]] = []
+    if args:
+        attrs_list.extend(args)
+    else:
+        attrs_list.extend(attr_dict.items())
+
+    def pa(s: str, l: int, tokens: ParseResults) -> None:
+        for attrName, attrValue in attrs_list:
+            if attrName not in tokens:
+                raise ParseException(s, l, f"no matching attribute {attrName!r}")
+            if attrValue != with_attribute.ANY_VALUE and tokens[attrName] != attrValue:  # type: ignore [attr-defined]
+                raise ParseException(
+                    s,
+                    l,
+                    f"attribute {attrName!r} has value {tokens[attrName]!r}, must be {attrValue!r}",
+                )
+
+    return pa
+
+
+with_attribute.ANY_VALUE = object()  # type: ignore [attr-defined]
+"Value to use with :class:`with_attribute` parse action, to match any value, as long as the attribute is present"
+
+
+def with_class(classname: str, namespace: str = "") -> ParseAction:
+    """
+    Simplified version of :meth:`with_attribute` when
+    matching on a div class - made difficult because ``class`` is
+    a reserved word in Python.
+
+    Using similar input data to the :meth:`with_attribute` examples:
+
+    .. testcode::
+
+       html = '''
+           <div>
+           Some text
+           <div class="grid">1 4 0 1 0</div>
+           <div class="graph">1,3 2,3 1,1</div>
+           <div>this &lt;div&gt; has no class</div>
+           </div>
+       '''
+       div,div_end = make_html_tags("div")
+
+    Only match div tag having the "grid" class:
+
+    .. testcode::
+
+       div_grid = div().set_parse_action(with_class("grid"))
+       grid_expr = div_grid + SkipTo(div | div_end)("body")
+       for grid_header in grid_expr.search_string(html):
+           print(grid_header.body)
+
+    prints:
+
+    .. testoutput::
+
+       1 4 0 1 0
+
+    Construct a match with any div tag having a class attribute,
+    regardless of the value:
+
+    .. testcode::
+
+       div_any_type = div().set_parse_action(
+           with_class(withAttribute.ANY_VALUE)
+       )
+       div_expr = div_any_type + SkipTo(div | div_end)("body")
+       for div_header in div_expr.search_string(html):
+           print(div_header.body)
+
+    prints:
+
+    .. testoutput::
+
+       1 4 0 1 0
+       1,3 2,3 1,1
+    """
+    classattr = f"{namespace}:class" if namespace else "class"
+    return with_attribute(**{classattr: classname})
+
+
+# Compatibility synonyms
+# fmt: off
+replaceWith = replaced_by_pep8("replaceWith", replace_with)
+removeQuotes = replaced_by_pep8("removeQuotes", remove_quotes)
+withAttribute = replaced_by_pep8("withAttribute", with_attribute)
+withClass = replaced_by_pep8("withClass", with_class)
+matchOnlyAtCol = replaced_by_pep8("matchOnlyAtCol", match_only_at_col)
+# fmt: on

package/lib/python3.14/site-packages/pyparsing/ai/best_practices.md

@@ -0,0 +1,75 @@
+<!-- 
+This file contains instructions for best practices for developing parsers with pyparsing, and can be used by AI agents
+when generating Python code using pyparsing.
+-->
+
+## Planning
+- If not provided or if target language definition is ambiguous, ask for examples of valid strings to be parsed
+- Before developing the pyparsing expressions, define a Backus-Naur Form definition and save this in docs/grammar.md. Update this document as changes are made in the parser.
+
+## Implementing
+- Import pyparsing using `import pyparsing as pp`, and use that for all pyparsing references.
+  - If referencing names from `pyparsing.common`, follow the pyparsing import with "ppc = pp.common" and use `ppc` as the namespace to access `pyparsing.common`.
+  - If referencing names from `pyparsing.unicode`, follow the pyparsing import with "ppu = pp.unicode" and use `ppu` as the namespace to access `pyparsing.unicode`.
+- When writing parsers that contain recursive elements (using `Forward()` or `infix_notation()`), immediately enable packrat parsing for performance: `pp.ParserElement.enable_packrat()` (call this right after importing pyparsing). See https://pyparsing-docs.readthedocs.io/en/latest/HowToUsePyparsing.html.
+  - For recursive grammars, define placeholders with `pp.Forward()` and assign later using the `<<=` operator; give Forwards meaningful names with `set_name()` to improve errors.
+- Use PEP8 method and argument names in the pyparsing API (`parse_string`, not `parseString`).
+- Do not include expressions for matching whitespace in the grammar. Pyparsing skips whitespace by default.
+- For line-oriented grammars where newlines are significant, set skippable whitespace to just spaces/tabs early: `pp.ParserElement.set_default_whitespace_chars(" \t")`, and define `NL = pp.LineEnd().suppress()` to handle line ends explicitly.
+- Prefer operator forms for readability: use +, |, ^, ~, etc., instead of explicit And/MatchFirst/Or/Not classes (see Usage notes in https://pyparsing-docs.readthedocs.io/en/latest/HowToUsePyparsing.html).
+- Use `set_name()` on all major grammar elements to support railroad diagramming and better error/debug output.
+- The grammar should be independently testable, without pulling in separate modules for data structures, evaluation, or command execution.
+- Use results names for robust access to parsed data fields; results names should be valid Python identifiers to support attribute-style access on returned ParseResults.
+  - Results names should take the place of numeric indexing into parsed results in most places.
+  - Define results names using call format not `set_results_name()`, example: `full_name = Word(alphas)("first_name") + Word(alphas)("last_name")`
+  - If adding results name to an expression that is contains one more sub-expressions with results names, the expression must be inclused in a Group.
+- Prefer `Keyword` over `Literal` for reserved words to avoid partial matches (e.g., `Keyword("for")` will not match the leading "for" in "format").
+  - Use `pp.CaselessKeyword`/`pp.CaselessLiteral` when keywords should match regardless of case.
+- When the full input must be consumed, call `parse_string` with `parse_all=True`.
+- If the grammar must handle comments, define an expression for them and use the `ignore()` method to skip them.
+  - Prefer built-ins like `pp.cpp_style_comment` and `pp.python_style_comment` for common comment syntaxes.
+- Use pyparsing `Group` to organize sub-expressions. Groups are also important for preserving results names when a sub-expression is used in a `OneOrMore` or `ZeroOrMore` expression.
+- Suppress punctuation tokens to keep results clean; a convenient pattern is `LBRACK, RBRACK, LBRACE, RBRACE, COLON = pp.Suppress.using_each("[]{}:")`.
+- For comma-separated sequences, prefer `pp.DelimitedList(...)`; wrap with `pp.Optional(...)` to allow empty lists or objects where appropriate.
+- For helper sub-expressions used only to build larger expressions, consider `set_name(None)` to keep result dumps uncluttered.
+- Use pyparsing `Each()` to define a list of elements that may occur in any order.
+  - The '&' operator is the operator form of Each and is often more readable when combining order-independent parts.
+- Use parse actions to do parse-time conversion of data from strings to useful data types.
+  - Use objects defined in pyparsing.common for common types like integer, real — these already have their conversion parse actions defined.
+  - For quoted strings, use `pp.dbl_quoted_string().set_parse_action(pp.remove_quotes)` to unquote automatically.
+  - Map reserved words to Python constants per this example for parsing "true" to auto-convert to a Python True: `pp.Keyword("true").set_parse_action(pp.replace_with(True))` (and similarly for false/null/etc.).
+  - When you want native Python containers from the parse, use `pp.Group(..., aslist=True)` for lists and `pp.Dict(..., asdict=True)` for dict-like data.
+- Use "using_each" with a list of keywords to define keyword constants, instead of separate assignments.
+- Choose the appropriate matching method:
+  - `parse_string()` parses from the start
+  - `search_string()` searches anywhere in the text
+  - `scan_string()` yields all matches with positions
+  - `transform_string()` is a convenience wrapper around `scan_string` to apply filters or transforms defined in parse actions, to perform batch transforms or conversions of expressions within a larger body of text
+- For line suffixes or directives, combine lookahead and slicing helpers: `pp.FollowedBy(...)` with `pp.rest_of_line`; when reusing a base expression with a different parse action, call `.copy()` before applying the new action to avoid side effects.
+- When defining a parser to be used in a REPL:
+  - add pyparsing `Tag()` elements of the form `Tag("command", <command-name>)` to each command definition to support model construction from parsed commands.
+  - define model classes using dataclasses, and use the "command" attribute in the parsed results to identify which model class to create. The model classes can then be used to construct the model from the ParseResults returned by parse_string(). Define the models in a separate parser_models.py file.
+- If defining the grammar as part of a Parser class, only the finished grammar needs to be implemented as an instance variable.
+- `ParseResults` support "in" testing for results names. Use "in" tests for the existence of results names, not `hasattr()`.
+- Avoid left recursion where possible. If you must support left-recursive grammars, enable it with `pp.ParserElement.enable_left_recursion()` and do not enable packrat at the same time (these modes are incompatible).
+- Use `pp.SkipTo` as a skipping expression to skip over arbitrary content.
+  - For example, `pp.SkipTo(pp.LineEnd())` will skip over all content until the end of the line; add a stop_on argument to SkipTo to stop skipping when a particular string is matched.
+  - Use `...` in place of simple SkipTo(expression)
+
+## Testing
+- Use the pyparsing `ParserElement.run_tests` method to run mini validation tests.
+  - Pass a single multiline string to `run_tests` to test the parser on multiple test input strings, each line is a separate test.
+  - You can add comments starting with "#" within the string passed to `run_tests` to document the individual test cases.
+  - To pass test input strings that span multiple lines, pass the test input strings as a list of strings.
+  - Pass `parse_all=True` to `run_tests` to test that the entire input is consumed.
+- When generating unit tests for the parser:
+  - generate tests that include presence and absence of optional elements
+  - use the methods in the mixin class pyparsing.testing.TestParseResultsAsserts to easily define expression, test input string, and expected results
+  - do not generate tests for invalid data
+
+## Debugging
+- If troubleshooting parse actions, use pyparsing's `trace_parse_action` decorator to echo arguments and return value
+- During development, call `pp.autoname_elements()` to auto-assign names to unnamed expressions to improve `dump()` and error messages.
+- Sub-expressions can be tested in isolation using `ParserElement.matches()`
+- When defined out of order, Literals can mistakenly match fragments: `Literal("for")` will match the leading "for" in "format". Can be corrected by using `Keyword` instead of `Literal`.
+- Dump the parsed results using `ParseResults.dump()`, `ParseResults.pprint()`, or `repr(ParseResults)`.

package/lib/python3.14/site-packages/pyparsing/ai/show_best_practices/__main__.py

@@ -0,0 +1,2 @@
+import pyparsing
+pyparsing.show_best_practices()