When I gave my presentation on pyparsing at PyCon '06, one of the questions after my talk was, "Is there anything you can't do with pyparsing?" This may have been a response to some of my posts to comp.lang.python, in which I recommended using pyparsing in many nontraditional applications, and often as an alternative to using regular expressions. I stammered a bit, and I mentioned that pyparsing is not always the best-suited tool— some data is already pretty well structured, and is better parsed using string indexing and
str.split(). I also do not recommend pyparsing for processing XML—there are already parsing and data access utilities out there, and applications that need XML typically need better performance than pyparsing will deliver.
But I think pyparsing is an excellent tool for developing command processors, web page scrapers, and parsers of text datafiles (such as logfiles or analysis output files). Pyparsing has been embedded in several popular Python add-on modules; go to the pyparsing wiki (http://pyparsing.wikispaces.com/whosusingpyparsing) for links to the latest ones.
I've written some documentation for pyparsing, but I have probably spent more time developing code examples that demonstrate various pyparsing code techniques. My experience has been that many developers want to see a selection of source code, and then adapt it to their problem at hand. Recently, I've started getting email asking for more formal usage documentation, so I hope this Short Cut ...