Stage for 2.2.1 release; add Getting Started section to module docstr…

…ing; fix Literal/Keyword index error bug

CHANGES

@@ -2,15 +2,31 @@
 Change Log
 ==========
 
-Version 2.2.1 - TBD
----------------------------
+Version 2.2.1 - September, 2018
+-------------------------------
+- Applied changes necessary to migrate hosting of pyparsing source
+  over to GitHub. Many thanks for help and contributions from hugovk,
+  jdufresne, and cngkaygusuz among others through this transition,
+  sorry it took me so long!
+
+- Fixed import of collections.abc to address DeprecationWarnings
+  in Python 3.7.
+
 - Updated oc.py example to support function calls in arithmetic
   expressions; fixed regex for '==' operator; and added packrat
   parsing. Raised on the pyparsing wiki by Boris Marin, thanks!
 
 - Fixed bug in select_parser.py example, group_by_terms was not
   reported. Reported on SF bugs by Adam Groszer, thanks Adam!
 
+- Added "Getting Started" section to the module docstring, to 
+  guide new users to the most common starting points in pyparsing's
+  API.
+
+- Fixed bug in Literal and Keyword classes, which erroneously
+  raised IndexError instead of ParseException.
+
+
 Version 2.2.0 - March, 2017
 ---------------------------
 - Bumped minor version number to reflect compatibility issues with

pyparsing.py

@@ -1,6 +1,6 @@
 # module pyparsing.py
 #
-# Copyright (c) 2003-2016  Paul T. McGuire
+# Copyright (c) 2003-2018  Paul T. McGuire
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
@@ -25,6 +25,7 @@
 __doc__ = \
 """
 pyparsing module - Classes and methods to define and execute parsing grammars
+=============================================================================
 
 The pyparsing module is an alternative approach to creating and executing simple grammars,
 vs. the traditional lex/yacc approach, or the use of regular expressions.  With pyparsing, you
@@ -58,10 +59,23 @@ class names, and the use of '+', '|' and '^' operators.
  - extra or missing whitespace (the above program will also handle "Hello,World!", "Hello  ,  World  !", etc.)
  - quoted strings
  - embedded comments
+
+
+Getting Started -
+-----------------
+Visit the classes L{ParserElement} and L{ParseResults} to see the base classes that most other pyparsing
+classes inherit from. Use the docstrings for examples of how to:
+ - construct literal match expressions from L{Literal} and L{CaselessLiteral} classes
+ - construct character word-group expressions using the L{Word} class
+ - see how to create repetitive expressions using L{ZeroOrMore} and L{OneOrMore} classes
+ - use L{'+'<And>}, L{'|'<MatchFirst>}, L{'^'<Or>}, and L{'&'<Each>} operators to combine simple expressions into more complex ones
+ - associate names with your parsed results using L{ParserElement.setResultsName}
+ - find some helpful expression short-cuts like L{delimitedList} and L{oneOf}
+ - find more useful common expressions in the L{pyparsing_common} namespace class
 """
 
-__version__ = "2.2.0"
-__versionTime__ = "06 Mar 2017 02:06 UTC"
+__version__ = "2.2.1"
+__versionTime__ = "18 Sep 2018 00:49 UTC"
 __author__ = "Paul McGuire <ptmcg@users.sourceforge.net>"
 
 import string
@@ -1034,11 +1048,11 @@ def extract_stack(limit=0):
             # special handling for Python 3.5.0 - extra deep call stack by 1
             offset = -3 if system_version == (3,5,0) else -2
             frame_summary = traceback.extract_stack(limit=-offset+limit-1)[offset]
-            return [(frame_summary.filename, frame_summary.lineno)]
+            return [frame_summary[:2]]
         def extract_tb(tb, limit=0):
             frames = traceback.extract_tb(tb, limit=limit)
             frame_summary = frames[-1]
-            return [(frame_summary.filename, frame_summary.lineno)]
+            return [frame_summary[:2]]
     else:
         extract_stack = traceback.extract_stack
         extract_tb = traceback.extract_tb
@@ -1383,7 +1397,7 @@ def _parseNoCache( self, instring, loc, doActions=True, callPreParse=True ):
             else:
                 preloc = loc
             tokensStart = preloc
-            if self.mayIndexError or loc >= len(instring):
+            if self.mayIndexError or preloc >= len(instring):
                 try:
                     loc,tokens = self.parseImpl( instring, preloc, doActions )
                 except IndexError:
@@ -1417,7 +1431,6 @@ def _parseNoCache( self, instring, loc, doActions=True, callPreParse=True ):
                                                   self.resultsName,
                                                   asList=self.saveAsList and isinstance(tokens,(ParseResults,list)),
                                                   modal=self.modalResults )
-
         if debugging:
             #~ print ("Matched",self,"->",retTokens.asList())
             if (self.debugActions[1] ):
@@ -4402,7 +4415,7 @@ def traceParseAction(f):
 
         @traceParseAction
         def remove_duplicate_chars(tokens):
-            return ''.join(sorted(set(''.join(tokens)))
+            return ''.join(sorted(set(''.join(tokens))))
 
         wds = OneOrMore(wd).setParseAction(remove_duplicate_chars)
         print(wds.parseString("slkdjs sld sldd sdlf sdljf"))

unitTests.py

@@ -4,7 +4,7 @@
 #
 # Unit tests for pyparsing module
 #
-# Copyright 2002-2016, Paul McGuire
+# Copyright 2002-2018, Paul McGuire
 #
 #
 from unittest import TestCase, TestSuite, TextTestRunner
@@ -3395,6 +3395,19 @@ def runTest(self):
         print_(initials)
         assert len(initials) == 4 and all(c=='*' for c in initials), 'fail col test'
 
+class LiteralExceptionTest(ParseTestCase):
+    def runTest(self):
+        import pyparsing as pp
+
+        for cls in (pp.Literal, pp.CaselessLiteral, pp.Keyword, pp.CaselessKeyword,
+             pp.Word, pp.Regex):
+            expr = cls('xyz')#.setName('{}_expr'.format(cls.__name__.lower()))
+
+            try:
+                expr.parseString(' ')
+            except Exception as e:
+                print(cls.__name__, str(e))
+                assert isinstance(e, pp.ParseBaseException), "class {} raised wrong exception type {}".format(cls.__name__, type(e).__name__)
 
 class MiscellaneousParserTests(ParseTestCase):
     def runTest(self):