Doc updates, remove references to deprecated delimitedList and delimi…

…ted_list (use DelimitedList class)

docs/HowToUsePyparsing.rst

@@ -6,7 +6,7 @@ Using the pyparsing module
 :address: ptmcg.pm+pyparsing@gmail.com
 
 :revision: 3.1.0
-:date: March, 2023
+:date: April, 2023
 
 :copyright: Copyright |copy| 2003-2023 Paul McGuire.
 
@@ -36,7 +36,7 @@ directory of the pyparsing GitHub repo.
 **Note**: *In pyparsing 3.0, many method and function names which were
 originally written using camelCase have been converted to PEP8-compatible
 snake_case. So ``parseString()`` is being renamed to ``parse_string()``,
-``delimitedList`` to ``delimited_list``, and so on. You may see the old
+``delimitedList`` to DelimitedList_, and so on. You may see the old
 names in legacy parsers, and they will be supported for a time with
 synonyms, but the synonyms will be removed in a future release.*
 
@@ -234,7 +234,7 @@ Usage notes
 - Punctuation may be significant for matching, but is rarely of
   much interest in the parsed results.  Use the ``suppress()`` method
   to keep these tokens from cluttering up your returned lists of
-  tokens.  For example, ``delimited_list()`` matches a succession of
+  tokens.  For example, DelimitedList_ matches a succession of
   one or more expressions, separated by delimiters (commas by
   default), but only returns a list of the actual expressions -
   the delimiters are used for parsing, but are suppressed from the
@@ -361,7 +361,7 @@ methods for code to use are:
 - ``set_results_name(string, list_all_matches=False)`` - name to be given
   to tokens matching
   the element; if multiple tokens within
-  a repetition group (such as ``ZeroOrMore`` or ``delimited_list``) the
+  a repetition group (such as ZeroOrMore_ or DelimitedList_) the
   default is to return only the last matching token - if ``list_all_matches``
   is set to True, then a list of all the matching tokens is returned.
 
@@ -697,12 +697,30 @@ Expression subclasses
   been renamed to ``Opt``. A compatibility synonym ``Optional`` is defined,
   but will be removed in a future release.)
 
+.. _ZeroOrMore:
+
 - ``ZeroOrMore`` - similar to ``Opt``, but can be repeated; ``ZeroOrMore(expr)``
   can also be written as ``expr[...]``.
 
-- ``OneOrMore`` - similar to ``ZeroOrMore``, but at least one match must
+.. _OneOrMore:
+
+- ``OneOrMore`` - similar to ZeroOrMore_, but at least one match must
   be present; ``OneOrMore(expr)`` can also be written as ``expr[1, ...]``.
 
+.. _DelimitedList:
+
+- ``DelimitedList`` - used for
+  matching one or more occurrences of ``expr``, separated by ``delim``.
+  By default, the delimiters are suppressed, so the returned results contain
+  only the separate list elements.  Can optionally specify ``combine=True``,
+  indicating that the expressions and delimiters should be returned as one
+  combined value (useful for scoped variables, such as ``"a.b.c"``, or
+  ``"a::b::c"``, or paths such as ``"a/b/c"``). Can also optionally specify ``min` and ``max``
+  restrictions on the length of the list, and
+  ``allow_trailing_delim`` to accept a trailing delimiter at the end of the list.
+
+.. _FollowedBy:
+
 - ``FollowedBy`` - a lookahead expression, requires matching of the given
   expressions, but does not advance the parsing position within the input string
 
@@ -786,7 +804,7 @@ Special subclasses
 ------------------
 
 - ``Group`` - causes the matched tokens to be enclosed in a list;
-  useful in repeated elements like ``ZeroOrMore`` and ``OneOrMore`` to
+  useful in repeated elements like ZeroOrMore_ and OneOrMore_ to
   break up matched tokens into groups for each repeated pattern
 
 - ``Dict`` - like ``Group``, but also constructs a dictionary, using the
@@ -1032,15 +1050,6 @@ Miscellaneous attributes and methods
 Helper methods
 --------------
 
-- ``delimited_list(expr, delim=',')`` - convenience function for
-  matching one or more occurrences of expr, separated by delim.
-  By default, the delimiters are suppressed, so the returned results contain
-  only the separate list elements.  Can optionally specify ``combine=True``,
-  indicating that the expressions and delimiters should be returned as one
-  combined value (useful for scoped variables, such as ``"a.b.c"``, or
-  ``"a::b::c"``, or paths such as ``"a/b/c"``). Can also optionally specify
-  ``allow_trailing_delim`` to accept a trailing delimiter at the end of the list.
-
 - ``counted_array(expr)`` - convenience function for a pattern where an list of
   instances of the given expression are preceded by an integer giving the count of
   elements in the list.  Returns an expression that parses the leading integer,
@@ -1331,7 +1340,7 @@ Common string and token constants
 - ``html_comment`` - a comment block delimited by ``'<!--'`` and ``'-->'`` sequences; can span
   multiple lines, but does not support nesting of comments
 
-- ``comma_separated_list`` - similar to ``delimited_list``, except that the
+- ``comma_separated_list`` - similar to DelimitedList_, except that the
   list expressions can be any text value, or a quoted string; quoted strings can
   safely include commas without incorrectly breaking the string into two tokens
 

docs/make_sphinx_docs.bat

@@ -0,0 +1 @@
+sphinx-build.exe -M html . _build

docs/pyparsing_class_diagram.puml

@@ -22,7 +22,6 @@ class globals {
 quoted_string
 sgl_quoted_string
 dbl_quoted_string
-delimited_list()
 counted_array()
 match_previous_literal()
 match_previous_expr()
@@ -185,6 +184,7 @@ class Each
 
 class OneOrMore
 class ZeroOrMore
+class DelimitedList
 class SkipTo
 class Group
 class Forward {
@@ -246,6 +246,7 @@ ParseElementEnhance <|-- Located
 ParseElementEnhance <|--- _MultipleMatch
 _MultipleMatch <|-- OneOrMore
 _MultipleMatch <|-- ZeroOrMore
+ParseElementEnhance <|-- DelimitedList
 ParseElementEnhance <|--- NotAny
 ParseElementEnhance <|--- FollowedBy
 ParseElementEnhance <|--- PrecededBy

docs/whats_new_in_3_0_0.rst

@@ -406,7 +406,7 @@ Other new features
   common fields in URLs. See the updated ``urlExtractorNew.py`` file in the
   ``examples`` directory. Submitted by Wolfgang Fahl.
 
-- ``delimited_list`` now supports an additional flag ``allow_trailing_delim``,
+- ``DelimitedList`` now supports an additional flag ``allow_trailing_delim``,
   to optionally parse an additional delimiter at the end of the list.
   Submitted by Kazantcev Andrey.
 
@@ -675,7 +675,8 @@ counted_array                   countedArray
 cpp_style_comment               cppStyleComment
 dbl_quoted_string               dblQuotedString
 dbl_slash_comment               dblSlashComment
-delimited_list                  delimitedList
+DelimitedList                   delimitedList
+DelimitedList                   delimited_list
 dict_of                         dictOf
 html_comment                    htmlComment
 infix_notation                  infixNotation

pyparsing/__init__.py

@@ -88,7 +88,7 @@
    :class:`ParserElement.set_results_name`
  - access the parsed data, which is returned as a :class:`ParseResults`
    object
- - find some helpful expression short-cuts like :class:`delimited_list`
+ - find some helpful expression short-cuts like :class:`DelimitedList`
    and :class:`one_of`
  - find more useful common expressions in the :class:`pyparsing_common`
    namespace class

pyparsing/common.py

@@ -1,6 +1,6 @@
 # common.py
 from .core import *
-from .helpers import delimited_list, any_open_tag, any_close_tag
+from .helpers import DelimitedList, any_open_tag, any_close_tag
 from datetime import datetime
 
 
@@ -348,7 +348,7 @@ def strip_html_tags(s: str, l: int, tokens: ParseResults):
         .streamline()
         .set_name("commaItem")
     )
-    comma_separated_list = delimited_list(
+    comma_separated_list = DelimitedList(
         Opt(quoted_string.copy() | _commasepitem, default="")
     ).set_name("comma separated list")
     """Predefined expression of 1 or more printable words or quoted strings, separated by commas."""

pyparsing/core.py

@@ -3377,7 +3377,7 @@ class CharsNotIn(Token):
 
         # define a comma-separated-value as anything that is not a ','
         csv_value = CharsNotIn(',')
-        print(delimited_list(csv_value).parse_string("dkls,lsdkjf,s12 34,@!#,213"))
+        print(DelimitedList(csv_value).parse_string("dkls,lsdkjf,s12 34,@!#,213"))
 
     prints::
 
@@ -5702,11 +5702,11 @@ class Group(TokenConverter):
         ident = Word(alphas)
         num = Word(nums)
         term = ident | num
-        func = ident + Opt(delimited_list(term))
+        func = ident + Opt(DelimitedList(term))
         print(func.parse_string("fn a, b, 100"))
         # -> ['fn', 'a', 'b', '100']
 
-        func = ident + Group(Opt(delimited_list(term)))
+        func = ident + Group(Opt(DelimitedList(term)))
         print(func.parse_string("fn a, b, 100"))
         # -> ['fn', ['a', 'b', '100']]
     """
@@ -5842,7 +5842,7 @@ class Suppress(TokenConverter):
         ['a', 'b', 'c', 'd']
         ['START', 'relevant text ', 'END']
 
-    (See also :class:`delimited_list`.)
+    (See also :class:`DelimitedList`.)
     """
 
     def __init__(self, expr: Union[ParserElement, str], savelist: bool = False):

pyparsing/helpers.py

@@ -374,7 +374,7 @@ def ungroup(expr: ParserElement) -> ParserElement:
 
 def locatedExpr(expr: ParserElement) -> ParserElement:
     """
-    (DEPRECATED - future code should use the Located class)
+    (DEPRECATED - future code should use the :class:`Located` class)
     Helper to decorate a returned token with its starting and ending
     locations in the input string.
 
@@ -456,7 +456,7 @@ def nested_expr(
 
         c_function = (decl_data_type("type")
                       + ident("name")
-                      + LPAR + Opt(delimited_list(arg), [])("args") + RPAR
+                      + LPAR + Opt(DelimitedList(arg), [])("args") + RPAR
                       + code_body("body"))
         c_function.ignore(c_style_comment)
 
@@ -856,7 +856,7 @@ def parseImpl(self, instring, loc, doActions=True):
 
 def indentedBlock(blockStatementExpr, indentStack, indent=True, backup_stacks=[]):
     """
-    (DEPRECATED - use ``IndentedBlock`` class instead)
+    (DEPRECATED - use :class:`IndentedBlock` class instead)
     Helper method for defining space-delimited indentation blocks,
     such as those used to define block statements in Python source code.
 
@@ -1039,23 +1039,7 @@ def delimited_list(
     *,
     allow_trailing_delim: bool = False,
 ) -> ParserElement:
-    """Helper to define a delimited list of expressions - the delimiter
-    defaults to ','. By default, the list elements and delimiters can
-    have intervening whitespace, and comments, but this can be
-    overridden by passing ``combine=True`` in the constructor. If
-    ``combine`` is set to ``True``, the matching tokens are
-    returned as a single token string, with the delimiters included;
-    otherwise, the matching tokens are returned as a list of tokens,
-    with the delimiters suppressed.
-
-    If ``allow_trailing_delim`` is set to True, then the list may end with
-    a delimiter.
-
-    Example::
-
-        delimited_list(Word(alphas)).parse_string("aa,bb,cc") # -> ['aa', 'bb', 'cc']
-        delimited_list(Word(hexnums), delim=':', combine=True).parse_string("AA:BB:CC:DD:EE") # -> ['AA:BB:CC:DD:EE']
-    """
+    """(DEPRECATED - use :class:`DelimitedList` class)"""
     return DelimitedList(
         expr, delim, combine, min, max, allow_trailing_delim=allow_trailing_delim
     )
@@ -1075,9 +1059,12 @@ def delimited_list(
 javaStyleComment = java_style_comment
 pythonStyleComment = python_style_comment
 
-@replaced_by_pep8(delimited_list)
+@replaced_by_pep8(DelimitedList)
 def delimitedList(): ...
 
+@replaced_by_pep8(DelimitedList)
+def delimited_list(): ...
+
 @replaced_by_pep8(counted_array)
 def countedArray(): ...
 

pyparsing/results.py

@@ -103,7 +103,7 @@ class List(list):
             LBRACK, RBRACK = map(pp.Suppress, "[]")
             element = pp.Forward()
             item = ppc.integer
-            element_list = LBRACK + pp.delimited_list(element) + RBRACK
+            element_list = LBRACK + pp.DelimitedList(element) + RBRACK
 
             # add parse actions to convert from ParseResults to actual Python collection types
             def as_python_list(t):
@@ -720,7 +720,7 @@ def pprint(self, *args, **kwargs):
             num = Word(nums)
             func = Forward()
             term = ident | num | Group('(' + func + ')')
-            func <<= ident + Group(Optional(delimited_list(term)))
+            func <<= ident + Group(Optional(DelimitedList(term)))
             result = func.parse_string("fna a,b,(fnb c,d,200),100")
             result.pprint(width=40)
 

pyparsing/util.py

@@ -267,7 +267,12 @@ def _inner(*args, **kwargs):
     _inner.__doc__ = f"""Deprecated - use :class:`{fn.__name__}`"""
     _inner.__name__ = compat_name
     _inner.__annotations__ = fn.__annotations__
-    _inner.__kwdefaults__ = fn.__kwdefaults__
+    if isinstance(fn, types.FunctionType):
+        _inner.__kwdefaults__ = fn.__kwdefaults__
+    elif isinstance(fn, type) and hasattr(fn, "__init__"):
+        _inner.__kwdefaults__ = fn.__init__.__kwdefaults__
+    else:
+        _inner.__kwdefaults__ = None
     _inner.__qualname__ = fn.__qualname__
     return cast(C, _inner)