| 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>')``. |