mirror of
https://github.com/python/cpython.git
synced 2025-07-07 19:35:27 +00:00
831b6de6d7
* Remove getopt and optparse deprecation notices * Add new docs sections for command line app helper libraries * Add guidance on choosing a CLI parsing library to the optparse docs * Link to the new guidance from the argparse and getopt docs * Reword intro in docs section for superseded stdlib modules * Reframe the optparse->argparse guide as a migration guide rather than as an upgrade guide --------- Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
65 lines
2.9 KiB
ReStructuredText
65 lines
2.9 KiB
ReStructuredText
.. currentmodule:: argparse
|
|
|
|
.. _upgrading-optparse-code:
|
|
.. _migrating-optparse-code:
|
|
|
|
============================================
|
|
Migrating ``optparse`` code to ``argparse``
|
|
============================================
|
|
|
|
The :mod:`argparse` module offers several higher level features not natively
|
|
provided by the :mod:`optparse` module, including:
|
|
|
|
* Handling positional arguments.
|
|
* Supporting subcommands.
|
|
* Allowing alternative option prefixes like ``+`` and ``/``.
|
|
* Handling zero-or-more and one-or-more style arguments.
|
|
* Producing more informative usage messages.
|
|
* Providing a much simpler interface for custom ``type`` and ``action``.
|
|
|
|
Originally, the :mod:`argparse` module attempted to maintain compatibility
|
|
with :mod:`optparse`. However, the fundamental design differences between
|
|
supporting declarative command line option processing (while leaving positional
|
|
argument processing to application code), and supporting both named options
|
|
and positional arguments in the declarative interface mean that the
|
|
API has diverged from that of ``optparse`` over time.
|
|
|
|
As described in :ref:`choosing-an-argument-parser`, applications that are
|
|
currently using :mod:`optparse` and are happy with the way it works can
|
|
just continue to use ``optparse``.
|
|
|
|
Application developers that are considering migrating should also review
|
|
the list of intrinsic behavioural differences described in that section
|
|
before deciding whether or not migration is desirable.
|
|
|
|
For applications that do choose to migrate from :mod:`optparse` to :mod:`argparse`,
|
|
the following suggestions should be helpful:
|
|
|
|
* Replace all :meth:`optparse.OptionParser.add_option` calls with
|
|
:meth:`ArgumentParser.add_argument` calls.
|
|
|
|
* Replace ``(options, args) = parser.parse_args()`` with ``args =
|
|
parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
|
|
calls for the positional arguments. Keep in mind that what was previously
|
|
called ``options``, now in the :mod:`argparse` context is called ``args``.
|
|
|
|
* Replace :meth:`optparse.OptionParser.disable_interspersed_args`
|
|
by using :meth:`~ArgumentParser.parse_intermixed_args` instead of
|
|
:meth:`~ArgumentParser.parse_args`.
|
|
|
|
* Replace callback actions and the ``callback_*`` keyword arguments with
|
|
``type`` or ``action`` arguments.
|
|
|
|
* Replace string names for ``type`` keyword arguments with the corresponding
|
|
type objects (e.g. int, float, complex, etc).
|
|
|
|
* Replace :class:`optparse.Values` with :class:`Namespace` and
|
|
:exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
|
|
:exc:`ArgumentError`.
|
|
|
|
* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
|
|
the standard Python syntax to use dictionaries to format strings, that is,
|
|
``%(default)s`` and ``%(prog)s``.
|
|
|
|
* Replace the OptionParser constructor ``version`` argument with a call to
|
|
``parser.add_argument('--version', action='version', version='<the version>')``.
|