Issue 5719: optparse: please provide a usage example in the module docstring (original) (raw)

Please add a simple usage example to the module docstring in optparse.py. The example available in the Python library reference would suffice (see http://python.org/doc/current/library/optparse.html).

Rationale: optparse is convenient, but a bit unintuitive. As a single data point, it took me a couple of years until I started remembering the syntax without having to refer to the documentation (compare this with, e.g. the csv module which you'll remember how to use after reading the docs once). Intuitively I always typed pydoc optparse in a terminal window and was disappointed with the lack of examples. The online docs are good, but not as easy to reach as pydoc.

In my experience, it's quite often that when you reach for optparse you're alreay shaving a yak (solving a problem needed to solve the real problem), and the five extra mouse clicks needed to find optparse's docs in the browser are rather disruptive.