Debian Codegraph @

Doc/howto/argparse-optparse.rst

raw
1 .. currentmodule:: argparse
2
3 .. _upgrading-optparse-code:
4 .. _migrating-optparse-code:
5
6 ============================================
7 Migrating ``optparse`` code to ``argparse``
8 ============================================
9
10 The :mod:`argparse` module offers several higher level features not natively
11 provided by the :mod:`optparse` module, including:
12
13 * Handling positional arguments.
14 * Supporting subcommands.
15 * Allowing alternative option prefixes like ``+`` and ``/``.
16 * Handling zero-or-more and one-or-more style arguments.
17 * Producing more informative usage messages.
18 * Providing a much simpler interface for custom ``type`` and ``action``.
19
20 Originally, the :mod:`argparse` module attempted to maintain compatibility
21 with :mod:`optparse`. However, the fundamental design differences between
22 supporting declarative command line option processing (while leaving positional
23 argument processing to application code), and supporting both named options
24 and positional arguments in the declarative interface mean that the
25 API has diverged from that of ``optparse`` over time.
26
27 As described in :ref:`choosing-an-argument-parser`, applications that are
28 currently using :mod:`optparse` and are happy with the way it works can
29 just continue to use ``optparse``.
30
31 Application developers that are considering migrating should also review
32 the list of intrinsic behavioural differences described in that section
33 before deciding whether or not migration is desirable.
34
35 For applications that do choose to migrate from :mod:`optparse` to :mod:`argparse`,
36 the following suggestions should be helpful:
37
38 * Replace all :meth:`optparse.OptionParser.add_option` calls with
39 :meth:`ArgumentParser.add_argument` calls.
40
41 * Replace ``(options, args) = parser.parse_args()`` with ``args =
42 parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
43 calls for the positional arguments. Keep in mind that what was previously
44 called ``options``, now in the :mod:`argparse` context is called ``args``.
45
46 * Replace :meth:`optparse.OptionParser.disable_interspersed_args`
47 by using :meth:`~ArgumentParser.parse_intermixed_args` instead of
48 :meth:`~ArgumentParser.parse_args`.
49
50 * Replace callback actions and the ``callback_*`` keyword arguments with
51 ``type`` or ``action`` arguments.
52
53 * Replace string names for ``type`` keyword arguments with the corresponding
54 type objects (e.g. int, float, complex, etc).
55
56 * Replace :class:`optparse.Values` with :class:`Namespace` and
57 :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
58 :exc:`ArgumentError`.
59
60 * Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
61 the standard Python syntax to use dictionaries to format strings, that is,
62 ``%(default)s`` and ``%(prog)s``.
63
64 * Replace the OptionParser constructor ``version`` argument with a call to
65 ``parser.add_argument('--version', action='version', version='<the version>')``.