From 3f69a059b9e199c874fa3e50765d82fef59cc232 Mon Sep 17 00:00:00 2001
From: Steven Bethard <steven.bethard@gmail.com>
Date: Sat, 26 Mar 2011 19:59:02 +0100
Subject: [PATCH] Issue #8982: Improve the documentation for the argparse
 Namespace object. (Merge from 3.2.)

---
 Doc/library/argparse.rst | 21 ++++++++++++++++-----
 Misc/NEWS                |  6 ++++--
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index ce21442c3f9..459647b49c8 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1310,13 +1310,24 @@ of :data:`sys.argv`.  This can be accomplished by passing a list of strings to
    Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
 
 
-Custom namespaces
-^^^^^^^^^^^^^^^^^
+The Namespace object
+^^^^^^^^^^^^^^^^^^^^
+
+By default, :meth:`parse_args` will return a new object of type :class:`Namespace`
+where the necessary attributes have been set. This class is deliberately simple,
+just an :class:`object` subclass with a readable string representation. If you
+prefer to have dict-like view of the attributes, you can use the standard Python
+idiom via :func:`vars`::
+
+   >>> parser = argparse.ArgumentParser()
+   >>> parser.add_argument('--foo')
+   >>> args = parser.parse_args(['--foo', 'BAR'])
+   >>> vars(args)
+   {'foo': 'BAR'}
 
 It may also be useful to have an :class:`ArgumentParser` assign attributes to an
-already existing object, rather than the newly-created :class:`Namespace` object
-that is normally used.  This can be achieved by specifying the ``namespace=``
-keyword argument::
+already existing object, rather than a new :class:`Namespace` object.  This can
+be achieved by specifying the ``namespace=`` keyword argument::
 
    >>> class C(object):
    ...     pass
diff --git a/Misc/NEWS b/Misc/NEWS
index fe4c3ae25a9..3ed93da7810 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -235,6 +235,10 @@ Library
 - Issue #9509: argparse now properly handles IOErrors raised by
   argparse.FileType.
 
+- Issue #9348: Raise an early error if argparse nargs and metavar don't match.
+
+- Issue #8982: Improve the documentation for the argparse Namespace object.
+
 Extension Modules
 -----------------
 
@@ -1343,8 +1347,6 @@ Library
 - Issue #8374: Update the internal alias table in the :mod:`locale` module to
   cover recent locale changes and additions.
 
-- Issue #9348: Raise an early error if argparse nargs and metavar don't match.
-
 Extension Modules
 -----------------