[issue4827] optparse: Callback example 1 is confusing

[Jason Kankiewicz]

New submission from Jason Kankiewicz <jkankiewicz at acm.org>:

"Callback example 1: trivial callback" reads

    Here’s an example of a callback option that takes no arguments, and
simply records that the option was seen:

        def record_foo_seen(option, opt_str, value, parser):
            parser.saw_foo = True

        parser.add_option("--foo", action="callback",
callback=record_foo_seen)

but the following paragraph

    Of course, you could do that with the store_true action.

is wrong because

        parser.add_option("--foo", action="store_true", dest="saw_foo")

would actually be duplicated by

        def record_foo_seen(option, opt_str, value, parser):
            parser.values.saw_foo = True

        parser.add_option("--foo", action="callback",
callback=record_foo_seen)

For example:
>>> from optparse import OptionParser
>>> parser = OptionParser()
>>> def record_foo_seen(option, opt_str, value, parser):
...     parser.saw_foo = True
...
>>> parser.add_option("--foo", action="callback", callback=record_foo_seen)
<Option at 0xab4f58: --foo>
>>> parser.parse_args(['--foo'])
(<Values at 0xabb0f8: {}>, [])
>>> parser = OptionParser()
>>> parser.add_option("--foo", action="store_true", dest="saw_foo")
<Option at 0xabb1e8: --foo>
>>> parser.parse_args(['--foo'])
(<Values at 0xabb1c0: {'saw_foo': True}>, [])
>>> parser = OptionParser()
>>> def record_foo_seen(option, opt_str, value, parser):
...     parser.values.saw_foo = True
...
>>> parser.add_option("--foo", action="callback", callback=record_foo_seen)
<Option at 0xabb508: --foo>
>>> parser.parse_args(['--foo'])
(<Values at 0xabb3f0: {'saw_foo': True}>, [])

----------
assignee: georg.brandl
components: Documentation
messages: 79039
nosy: georg.brandl, jkankiewicz
severity: normal
status: open
title: optparse: Callback example 1 is confusing
versions: Python 2.4, Python 2.5, Python 2.6, Python 2.7, Python 3.0, Python 3.1

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue4827>
_______________________________________