summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Doc/library/argparse.rst1
-rw-r--r--Doc/whatsnew/3.2.rst61
2 files changed, 60 insertions, 2 deletions
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 63b25bb..0ca8aa0 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1729,6 +1729,7 @@ Exiting methods
This method prints a usage message including the *message* to the
standard output and terminates the program with a status code of 2.
+.. _upgrading-optparse-code:
Upgrading optparse code
-----------------------
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index 1493765..dcb6ef0 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -77,7 +77,7 @@ PEP 389: Argparse Command Line Parsing Module
A new module for command line parsing, :mod:`argparse`, was introduced to
overcome the limitations of :mod:`optparse` which did not provide support for
-positional arguments (not just option), subcommands, required options and other
+positional arguments (not just options), subcommands, required options and other
common patterns of specifying and validating options.
This module has already has wide-spread success in the community as a
@@ -86,13 +86,66 @@ third-party module. Being more fully featured than its predecessor,
older module is still being kept available because of the substantial amount of
legacy code that depends on it.
-.. XXX add examples that highlight the new features
+Here's an annotated example parser showing features like limiting results to a
+set of choices, specifying a *metavar* in the help screen, validating that one
+or more postional arguments is present, and making a required option::
+
+ import argparse
+ parser = argparse.ArgumentParser(
+ description = 'Manage servers', # main description for help
+ epilog = 'Tested on Solaris and Linux') # displayed after help
+ parser.add_argument('action', # argument name
+ choices = ['deploy', 'start', 'stop'], # one of four allowed values
+ help = 'action on each target') # help msg
+ parser.add_argument('targets',
+ metavar = 'HOSTNAME', # var name used in help msg
+ nargs = '+', # require 1 or more targets
+ help = 'url for target machines') # help msg explanation
+ parser.add_argument('-u', '--user', # -u or --user option
+ required = True, # make this a required argument
+ help = 'login as user')
+
+Example of calling the parser on a command string::
+
+ >>> cmd = 'deploy sneezy.example.com sleepy.example.com -u skycaptain'
+ >>> result = parser.parse_args(cmd.split())
+
+ >>> # parsed variable are stored in the attributes
+ >>> result.action
+ 'deploy'
+ >>> result.targets
+ ['sneezy.example.com', 'sleepy.example.com']
+ >>> result.user
+ 'skycaptain'
+
+Example of the parser's automatically generated help::
+
+ >>> parser.parse_args('-h'.split())
+
+ usage: tmp_argparse_example.py [-h] -u USER
+ {deploy,start,stop} HOSTNAME [HOSTNAME ...]
+
+ Manage servers
+
+ positional arguments:
+ {deploy,start,stop} action on each target
+ HOSTNAME url for target machines
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -u USER, --user USER login as user
+
+ Tested on Solaris and Linux
+
.. seealso::
:pep:`389` - New Command Line Parsing Module
PEP written by Steven Bethard.
+ :ref:`upgrading-optparse-code` for details on the differences from
+ :mod:`optparse`.
+
PEP 391: Dictionary Based Configuration for Logging
====================================================
@@ -992,6 +1045,10 @@ The docs now contain more examples and recipes. In particular, :mod:`re` module
has an extensive section, :ref:`re-examples`. Likewise, the :mod:`itertools`
module continues to be updated with new :ref:`itertools-recipes`.
+The :mod:`datetime` module now has an auxiliary implementation in pure Python.
+No functionality was changed. This just provides an easier-to-read
+alternate implementation. (Contributed by Alexander Belopolsky.)
+
IDLE
====