Merged revisions 79349,79381,79412,79801,79818 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r79349 | andrew.kuchling | 2010-03-23 20:39:24 +0200 (Tue, 23 Mar 2010) | 1 line

  add some unittest items
........
  r79381 | andrew.kuchling | 2010-03-24 20:07:43 +0200 (Wed, 24 Mar 2010) | 1 line

  Various edits
........
  r79412 | andrew.kuchling | 2010-03-25 03:35:51 +0200 (Thu, 25 Mar 2010) | 1 line

  Add various items
........
  r79801 | tarek.ziade | 2010-04-05 17:58:14 +0300 (Mon, 05 Apr 2010) | 1 line

  added a note for Andrew, about distutils2
........
  r79818 | ezio.melotti | 2010-04-06 06:26:49 +0300 (Tue, 06 Apr 2010) | 1 line

  Fix several links and other mistakes.
........

1 files changed, 272 insertions, 186 deletions

diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index 329518d..dcea4f2 100644
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -8,6 +8,9 @@
 
 .. Fix accents on Kristjan Valur Jonsson, Fuerstenau
 
+.. Big jobs: argparse, ElementTree 1.3, pep 391, 3106, sysconfig
+..  unittest test discovery
+
 .. $Id$
    Rules for maintenance:
 
@@ -37,7 +40,7 @@
    * You can comment out your additions if you like, but it's not
    necessary (especially when a final release is some months away).
 
-   * Credit the author of a patch or bugfix.   Just the name is
+   * Credit the author of a patch or bugfix.  Just the name is
    sufficient; the e-mail address isn't necessary.
 
    * It's helpful to add the bug/patch number in a parenthetical comment.
@@ -106,11 +109,12 @@ Regular Python dictionaries iterate over key/value pairs in arbitrary order.
 Over the years, a number of authors have written alternative implementations
 that remember the order that the keys were originally inserted.  Based on
 the experiences from those implementations, a new
-:class:`collections.OrderedDict` class has been introduced.
+:class:`~collections.OrderedDict` class has been introduced in the
+:mod:`collections` module.
 
-The :class:`OrderedDict` API is substantially the same as regular dictionaries
-but will iterate over keys and values in a guaranteed order depending on
-when a key was first inserted::
+The :class:`~collections.OrderedDict` API is substantially the same as regular
+dictionaries but will iterate over keys and values in a guaranteed order
+depending on when a key was first inserted::
 
     >>> from collections import OrderedDict
     >>> d = OrderedDict([('first', 1), ('second', 2),
@@ -132,8 +136,8 @@ Deleting an entry and reinserting it will move it to the end::
     >>> d.items()
     [('first', 1), ('third', 3), ('second', 5)]
 
-The :meth:`popitem` method has an optional *last* argument
-that defaults to True.  If *last* is True, the most recently
+The :meth:`~collections.OrderedDict.popitem` method has an optional *last*
+argument that defaults to True.  If *last* is True, the most recently
 added key is returned and removed; if it's False, the
 oldest key is selected::
 
@@ -142,9 +146,9 @@ oldest key is selected::
     (19, 0)
     >>> od.popitem()
     (18, 0)
-    >>> od.popitem(False)
+    >>> od.popitem(last=False)
     (0, 0)
-    >>> od.popitem(False)
+    >>> od.popitem(last=False)
     (1, 0)
 
 Comparing two ordered dictionaries checks both the keys and values,
@@ -154,31 +158,35 @@ and requires that the insertion order was the same::
     ...                    ('third', 3)])
     >>> od2 = OrderedDict([('third', 3), ('first', 1),
     ...                    ('second', 2)])
-    >>> od1==od2
+    >>> od1 == od2
     False
     >>> # Move 'third' key to the end
-    >>> del od2['third'] ; od2['third'] = 3
-    >>> od1==od2
+    >>> del od2['third']; od2['third'] = 3
+    >>> od1 == od2
     True
 
-Comparing an :class:`OrderedDict` with a regular dictionary
+Comparing an :class:`~collections.OrderedDict` with a regular dictionary
 ignores the insertion order and just compares the keys and values.
 
-How does the :class:`OrderedDict` work?  It maintains a doubly-linked
-list of keys, appending new keys to the list as they're inserted.  A
-secondary dictionary maps keys to their corresponding list node, so
+How does the :class:`~collections.OrderedDict` work?  It maintains a
+doubly-linked list of keys, appending new keys to the list as they're inserted.
+A secondary dictionary maps keys to their corresponding list node, so
 deletion doesn't have to traverse the entire linked list and therefore
 remains O(1).
 
 .. XXX check O(1)-ness with Raymond
+..     Also check if the 'somenamedtuple' in the collection module should
+..     be replaced/removed in order to use
+..     :meth:`~collections.namedtuple._asdict()` (see below)
 
 The standard library now supports use of ordered dictionaries in several
 modules.  The :mod:`configparser` module uses them by default.  This lets
 configuration files be read, modified, and then written back in their original
-order.  The *_asdict()* method for :func:`collections.namedtuple` now
-returns an ordered dictionary with the values appearing in the same order as
-the underlying tuple indicies.  The :mod:`json` module is being built-out with
-an *object_pairs_hook* to allow OrderedDicts to be built by the decoder.
+order.  The :meth:`~collections.somenamedtuple._asdict()` method for
+:func:`collections.namedtuple` now returns an ordered dictionary with the
+values appearing in the same order as the underlying tuple indices.
+The :mod:`json` module is being built-out with an *object_pairs_hook* to allow
+OrderedDicts to be built by the decoder.
 Support was also added for third-party tools like `PyYAML <http://pyyaml.org/>`_.
 
 .. seealso::
@@ -190,7 +198,7 @@ Support was also added for third-party tools like `PyYAML <http://pyyaml.org/>`_
 .. _pep-0378:
 
 PEP 378: Format Specifier for Thousands Separator
-====================================================
+=================================================
 
 To make program output more readable, it can be useful to add
 separators to large numbers and render them as
@@ -203,7 +211,7 @@ to use and unsuitable for multi-threaded applications where different
 threads are producing output for different locales.
 
 Therefore, a simple comma-grouping mechanism has been added to the
-mini-language used by the string :meth:`format` method.  When
+mini-language used by the :meth:`str.format` method.  When
 formatting a floating-point number, simply include a comma between the
 width and the precision::
 
@@ -242,6 +250,20 @@ PEP 391: Dictionary-Based Configuration For Logging
 
 XXX write this section.
 
+Two smaller enhancements to the logging module are:
+
+.. rev79293
+
+* :class:`Logger` instances gained a :meth:`getChild` that retrieves a
+  descendant logger using a relative path.  For example,
+  once you retrieve a logger by doing ``log = getLogger('app')``,
+  calling ``log.getChild('network.listen')`` is equivalent to
+  ``getLogger('app.network.listen')``.
+
+* The :class:`LoggerAdapter` class gained a :meth:`isEnabledFor` method
+  that takes a *level* and returns whether the underlying logger would
+  process a message of that level of importance.
+
 .. seealso::
 
    :pep:`391` - Dictionary-Based Configuration For Logging
@@ -273,9 +295,9 @@ Some smaller changes made to the core Python language are:
 
     >>> {1,2,3,4,5}
     set([1, 2, 3, 4, 5])
-    >>> set()
+    >>> set() # empty set
     set([])
-    >>> {}
+    >>> {}    # empty dict
     {}
 
   Backported by Alexandre Vassalotti; :issue:`2335`.
@@ -321,7 +343,7 @@ Some smaller changes made to the core Python language are:
   :mod:`marshal`, :mod:`pickle`
   and :mod:`json` modules;
   parsing of float and imaginary literals in Python code;
-  and :class:`Decimal`-to-float conversion.
+  and :class:`~decimal.Decimal`-to-float conversion.
 
   Related to this, the :func:`repr` of a floating-point number *x*
   now returns a result based on the shortest decimal string that's
@@ -329,6 +351,8 @@ Some smaller changes made to the core Python language are:
   round-half-to-even rounding mode).  Previously it gave a string
   based on rounding x to 17 decimal digits.
 
+  .. maybe add an example?
+
   The rounding library responsible for this improvement works on
   Windows, and on Unix platforms using the gcc, icc, or suncc
   compilers.  There may be a small number of platforms where correct
@@ -356,11 +380,12 @@ Some smaller changes made to the core Python language are:
   of them -- but you can mix auto-numbering and named fields, as in the second
   example above.  (Contributed by Eric Smith; :issue:`5237`.)
 
-  Complex numbers now correctly support usage with :func:`format`.
+  Complex numbers now correctly support usage with :func:`format`,
+  and default to being right-aligned.
   Specifying a precision or comma-separation applies to both the real
   and imaginary parts of the number, but a specified field width and
   alignment is applied to the whole of the resulting ``1.5+3j``
-  output.  (Contributed by Eric Smith; :issue:`1588`.)
+  output.  (Contributed by Eric Smith; :issue:`1588` and :issue:`7988`.)
 
   The 'F' format code now always formats its output using uppercase characters,
   so it will now produce 'INF' and 'NAN'.
@@ -371,7 +396,7 @@ Some smaller changes made to the core Python language are:
   its argument in binary::
 
       >>> n = 37
-      >>> bin(37)
+      >>> bin(n)
       '0b100101'
       >>> n.bit_length()
       6
@@ -402,8 +427,7 @@ Some smaller changes made to the core Python language are:
     >>> n = 295147905179352891391
     >>> float(n)
     2.9514790517935289e+20
-    >>> n-long(float(n)
-    ... )
+    >>> n - long(float(n))
     -1L
 
   (Implemented by Mark Dickinson; :issue:`3166`.)
@@ -411,10 +435,16 @@ Some smaller changes made to the core Python language are:
   Integer division is also more accurate in its rounding behaviours.  (Also
   implemented by Mark Dickinson; :issue:`1811`.)
 
-* The :class:`bytearray` type's :meth:`translate` method now accepts
+* It's now possible for a subclass of the built-in :class:`unicode` type
+  to override the :meth:`__unicode__` method.  (Implemented by
+  Victor Stinner; :issue:`1583863`.)
+
+* The :class:`bytearray` type's :meth:`~bytearray.translate` method now accepts
   ``None`` as its first argument.  (Fixed by Georg Brandl;
   :issue:`4759`.)
 
+  .. bytearray doesn't seem to be documented
+
 * When using ``@classmethod`` and ``@staticmethod`` to wrap
   methods as class or static methods, the wrapper object now
   exposes the wrapped function as their :attr:`__func__` attribute.
@@ -473,7 +503,7 @@ Several performance enhancements have been added:
   the middle generation has been collected 10 times and when the
   number of survivor objects from the middle generation exceeds 10% of
   the number of objects in the oldest generation.  (Suggested by Martin
-  von Loewis and implemented by Antoine Pitrou; :issue:`4074`.)
+  von Löwis and implemented by Antoine Pitrou; :issue:`4074`.)
 
 * The garbage collector tries to avoid tracking simple containers
   which can't be part of a cycle. In Python 2.7, this is now true for
@@ -495,7 +525,7 @@ Several performance enhancements have been added:
 
   Apart from the performance improvements this change should be
   invisible to end users, with one exception: for testing and
-  debugging purposes there's a new structseq ``sys.long_info`` that
+  debugging purposes there's a new structseq :data:`sys.long_info` that
   provides information about the internal format, giving the number of
   bits per digit and the size in bytes of the C type used to store
   each digit::
@@ -561,7 +591,7 @@ changes, sorted alphabetically by module name. Consult the
 :file:`Misc/NEWS` file in the source tree for a more complete list of
 changes, or look through the Subversion logs for all the details.
 
-* The :mod:`bdb` module's base debugging class :class:`Bdb`
+* The :mod:`bdb` module's base debugging class :class:`~bdb.Bdb`
   gained a feature for skipping modules.  The constructor
   now takes an iterable containing glob-style patterns such as
   ``django.*``; the debugger will not step into stack frames
@@ -573,13 +603,21 @@ changes, or look through the Subversion logs for all the details.
   used with :class:`memoryview` instances and other similar buffer objects.
   (Backported from 3.x by Florent Xicluna; :issue:`7703`.)
 
-* The :mod:`bz2` module's :class:`BZ2File` now supports the context
+* Updated module: the :mod:`bsddb` module has been updated from 4.7.2devel9
+  to version 4.8.4 of
+  `the pybsddb package <http://www.jcea.es/programacion/pybsddb.htm>`__.
+  The new version features better Python 3.x compatibility, various bug fixes,
+  and adds several new BerkeleyDB flags and methods.
+  (Updated by Jesús Cea Avión; :issue:`8156`.  The pybsddb
+  changelog can be browsed at http://hg.jcea.es/pybsddb/file/tip/ChangeLog.)
+
+* The :mod:`bz2` module's :class:`~bz2.BZ2File` now supports the context
   management protocol, so you can write ``with bz2.BZ2File(...) as f: ...``.
   (Contributed by Hagen Fuerstenau; :issue:`3860`.)
 
-* New class: the :class:`Counter` class in the :mod:`collections` module is
-  useful for tallying data.  :class:`Counter` instances behave mostly
-  like dictionaries but return zero for missing keys instead of
+* New class: the :class:`~collections.Counter` class in the :mod:`collections`
+  module is useful for tallying data.  :class:`~collections.Counter` instances
+  behave mostly like dictionaries but return zero for missing keys instead of
   raising a :exc:`KeyError`:
 
   .. doctest::
@@ -599,8 +637,9 @@ changes, or look through the Subversion logs for all the details.
      >>> c['z']
      0
 
-  There are two additional :class:`Counter` methods: :meth:`most_common`
-  returns the N most common elements and their counts, and :meth:`elements`
+  There are two additional :class:`~collections.Counter` methods:
+  :meth:`~collections.Counter.most_common` returns the N most common elements
+  and their counts, and :meth:`~collections.Counter.elements`
   returns an iterator over the contained element, repeating each element
   as many times as its count::
 
@@ -612,12 +651,14 @@ changes, or look through the Subversion logs for all the details.
        'h', 'h', 'm', 'l', 'l', 'o', 'n', 'p', 's',
        's', 's', 'r', 't', 't', 'x'
 
+  .. maybe it's better to use list(c.elements()) here
+
   Contributed by Raymond Hettinger; :issue:`1696199`.
 
-  The new `~collections.OrderedDict` class is described in the earlier section
-  :ref:`pep-0372`.
+  The new :class:`~collections.OrderedDict` class is described in the earlier
+  section :ref:`pep-0372`.
 
-  The :class:`namedtuple` class now has an optional *rename* parameter.
+  The :class:`~collections.namedtuple` class now has an optional *rename* parameter.
   If *rename* is true, field names that are invalid because they've
   been repeated or that aren't legal Python identifiers will be
   renamed to legal names that are derived from the field's
@@ -630,12 +671,12 @@ changes, or look through the Subversion logs for all the details.
 
   (Added by Raymond Hettinger; :issue:`1818`.)
 
-  The :class:`deque` data type now exposes its maximum length as the
-  read-only :attr:`maxlen` attribute, and has a
-  :meth:`reverse` method that reverses the elements of the deque in-place.
+  The :class:`~collections.deque` data type now exposes its maximum length as the
+  read-only :attr:`~collections.deque.maxlen` attribute, and has a
+  :meth:`~collections.deque.reverse` method that reverses the elements of the deque in-place.
   (Added by Raymond Hettinger.)
 
-* The :mod:`copy` module's :func:`deepcopy` function will now
+* The :mod:`copy` module's :func:`~copy.deepcopy` function will now
   correctly copy bound instance methods.  (Implemented by
   Robert Collins; :issue:`1515`.)
 
@@ -646,13 +687,13 @@ changes, or look through the Subversion logs for all the details.
   3.0.9, containing various fixes for different platforms.  (Updated
   by Matthias Klose; :issue:`8142`.)
 
-* New method: the :mod:`datetime` module's :class:`timedelta` class
-  gained a :meth:`total_seconds` method that returns the number of seconds
-  in the duration.  (Contributed by Brian Quinlan; :issue:`5788`.)
+* New method: the :mod:`datetime` module's :class:`~datetime.timedelta` class
+  gained a :meth:`~datetime.timedelta.total_seconds` method that returns the
+  number of seconds in the duration.  (Contributed by Brian Quinlan; :issue:`5788`.)
 
-* New method: the :class:`Decimal` class gained a
-  :meth:`from_float` class method that performs an exact conversion
-  of a floating-point number to a :class:`Decimal`.
+* New method: the :class:`~decimal.Decimal` class gained a
+  :meth:`~decimal.Decimal.from_float` class method that performs an exact
+  conversion of a floating-point number to a :class:`~decimal.Decimal`.
   Note that this is an **exact** conversion that strives for the
   closest decimal approximation to the floating-point representation's value;
   the resulting decimal value will therefore still include the inaccuracy,
@@ -661,32 +702,39 @@ changes, or look through the Subversion logs for all the details.
   ``Decimal('0.1000000000000000055511151231257827021181583404541015625')``.
   (Implemented by Raymond Hettinger; :issue:`4796`.)
 
-  The constructor for :class:`Decimal` now accepts non-European
+  Most of the methods of the :class:`~decimal.Context` class now accept integers
+  as well as :class:`~decimal.Decimal` instances; the only exceptions are the
+  :meth:`~decimal.Context.canonical` and :meth:`~decimal.Context.is_canonical`
+  methods.  (Patch by Juan José Conti; :issue:`7633`.)
+
+  The constructor for :class:`~decimal.Decimal` now accepts non-European
   Unicode characters, such as Arabic-Indic digits.  (Contributed by
   Mark Dickinson; :issue:`6595`.)
 
-  When using :class:`Decimal` instances with a string's
-  :meth:`format` method, the default alignment was previously
+  When using :class:`~decimal.Decimal` instances with a string's
+  :meth:`~str.format` method, the default alignment was previously
   left-alignment.  This has been changed to right-alignment, which seems
   more sensible for numeric types.  (Changed by Mark Dickinson; :issue:`6857`.)
 
-* The :class:`Fraction` class now accepts two rational numbers
+* The :class:`~fractions.Fraction` class now accepts two rational numbers
   as arguments to its constructor.
   (Implemented by Mark Dickinson; :issue:`5812`.)
 
-* The :mod:`ftplib` module gained the ability to establish secure FTP
+* New class: a new :class:`~ftplib.FTP_TLS` class in
+  the :mod:`ftplib` module provides secure FTP
   connections using TLS encapsulation of authentication as well as
-  subsequent control and data transfers.  This is provided by the new
-  :class:`ftplib.FTP_TLS` class.
-  (Contributed by Giampaolo Rodola', :issue:`2054`.)  The :meth:`storbinary`
-  method for binary uploads can now restart uploads thanks to an added
-  *rest* parameter (patch by Pablo Mouzo; :issue:`6845`.)
+  subsequent control and data transfers.
+  (Contributed by Giampaolo Rodola', :issue:`2054`.)
+
+  The :meth:`~ftplib.FTP.storbinary` method for binary uploads can now restart
+  uploads thanks to an added *rest* parameter (patch by Pablo Mouzo;
+  :issue:`6845`.)
 
-* New function: the :mod:`gc` module's :func:`is_tracked` returns
+* New function: the :mod:`gc` module's :func:`~gc.is_tracked` returns
   true if a given instance is tracked by the garbage collector, false
   otherwise. (Contributed by Antoine Pitrou; :issue:`4688`.)
 
-* The :mod:`gzip` module's :class:`GzipFile` now supports the context
+* The :mod:`gzip` module's :class:`~gzip.GzipFile` now supports the context
   management protocol, so you can write ``with gzip.GzipFile(...) as f: ...``
   (contributed by Hagen Fuerstenau; :issue:`3860`), and it now implements
   the :class:`io.BufferedIOBase` ABC, so you can wrap it with
@@ -700,11 +748,17 @@ changes, or look through the Subversion logs for all the details.
   :mod:`gzip` module will now consume these trailing bytes.  (Fixed by
   Tadek Pietraszek and Brian Curtin; :issue:`2846`.)
 
-* The default :class:`HTTPResponse` class used by the :mod:`httplib` module now
+* New attribute: the :mod:`hashlib` module now has an :attr:`~hashlib.hashlib.algorithms`
+  attribute containing a tuple naming the supported algorithms.
+  In Python 2.7, ``hashlib.algorithms`` contains
+  ``('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512')``
+  (Contributed by Carl Chenet; :issue:`7418`.)
+
+* The default :class:`~httplib.HTTPResponse` class used by the :mod:`httplib` module now
   supports buffering, resulting in much faster reading of HTTP responses.
   (Contributed by Kristjan Valur Jonsson; :issue:`4879`.)
 
-  The :class:`HTTPConnection` and :class:`HTTPSConnection` classes
+  The :class:`~httplib.HTTPConnection` and :class:`~httplib.HTTPSConnection` classes
   now support a *source_address* parameter, a ``(host, port)`` 2-tuple
   giving the source address that will be used for the connection.
   (Contributed by Eldon Ziegler; :issue:`3972`.)
@@ -712,9 +766,9 @@ changes, or look through the Subversion logs for all the details.
 * The :mod:`imaplib` module now supports IPv6 addresses.
   (Contributed by Derek Morr; :issue:`1655`.)
 
-* The :mod:`io` library has been upgraded to the version shipped with
+* Updated module: The :mod:`io` library has been upgraded to the version shipped with
   Python 3.1.  For 3.1, the I/O library was entirely rewritten in C
-  and is 2 to 20 times faster depending on the task at hand.  The
+  and is 2 to 20 times faster depending on the task being performed.  The
   original Python version was renamed to the :mod:`_pyio` module.
 
   One minor resulting change: the :class:`io.TextIOBase` class now
@@ -724,7 +778,7 @@ changes, or look through the Subversion logs for all the details.
 
   The :class:`io.FileIO` class now raises an :exc:`OSError` when passed
   an invalid file descriptor.  (Implemented by Benjamin Peterson;
-  :issue:`4991`.)  The :meth:`truncate` method now preserves the
+  :issue:`4991`.)  The :meth:`~io.IOBase.truncate` method now preserves the
   file position; previously it would change the file position to the
   end of the new file.  (Fixed by Pascal Chambon; :issue:`6939`.)
 
@@ -735,9 +789,11 @@ changes, or look through the Subversion logs for all the details.
     itertools.compress('ABCDEF', [1,0,1,0,1,1]) =>
       A, C, E, F
 
+  .. maybe here is better to use >>> list(itertools.compress(...)) instead
+
   New function: ``itertools.combinations_with_replacement(iter, r)``
   returns all the possible *r*-length combinations of elements from the
-  iterable *iter*.  Unlike :func:`combinations`, individual elements
+  iterable *iter*.  Unlike :func:`~itertools.combinations`, individual elements
   can be repeated in the generated combinations::
 
     itertools.combinations_with_replacement('abc', 2) =>
@@ -747,10 +803,10 @@ changes, or look through the Subversion logs for all the details.
   Note that elements are treated as unique depending on their position
   in the input, not their actual values.
 
-  The :class:`itertools.count` function now has a *step* argument that
-  allows incrementing by values other than 1.  :func:`count` also
+  The :func:`itertools.count` function now has a *step* argument that
+  allows incrementing by values other than 1.  :func:`~itertools.count` also
   now allows keyword arguments, and using non-integer values such as
-  floats or :class:`Decimal` instances.  (Implemented by Raymond
+  floats or :class:`~decimal.Decimal` instances.  (Implemented by Raymond
   Hettinger; :issue:`5032`.)
 
   :func:`itertools.combinations` and :func:`itertools.product` were
@@ -758,22 +814,22 @@ changes, or look through the Subversion logs for all the details.
   the input iterable.  This was deemed a specification error, so they
   now return an empty iterator.  (Fixed by Raymond Hettinger; :issue:`4816`.)
 
-* The :mod:`json` module was upgraded to version 2.0.9 of the
+* Updated module: The :mod:`json` module was upgraded to version 2.0.9 of the
   simplejson package, which includes a C extension that makes
   encoding and decoding faster.
   (Contributed by Bob Ippolito; :issue:`4136`.)
 
-  To support the new :class:`OrderedDict` type, :func:`json.load`
+  To support the new :class:`collections.OrderedDict` type, :func:`json.load`
   now has an optional *object_pairs_hook* parameter that will be called
   with any object literal that decodes to a list of pairs.
   (Contributed by Raymond Hettinger; :issue:`5381`.)
 
 * New functions: the :mod:`math` module gained
-  :func:`erf` and :func:`erfc` for the error function and the complementary error function,
-  :func:`expm1` which computes ``e**x - 1`` with more precision than
-  using :func:`exp` and subtracting 1,
-  :func:`gamma` for the Gamma function, and
-  :func:`lgamma` for the natural log of the Gamma function.
+  :func:`~math.erf` and :func:`~math.erfc` for the error function and the complementary error function,
+  :func:`~math.expm1` which computes ``e**x - 1`` with more precision than
+  using :func:`~math.exp` and subtracting 1,
+  :func:`~math.gamma` for the Gamma function, and
+  :func:`~math.lgamma` for the natural log of the Gamma function.
   (Contributed by Mark Dickinson and nirinA raseliarison; :issue:`3366`.)
 
 * The :mod:`multiprocessing` module's :class:`Manager*` classes
@@ -782,10 +838,10 @@ changes, or look through the Subversion logs for all the details.
   passed to the callable.
   (Contributed by lekma; :issue:`5585`.)
 
-  The :class:`Pool` class, which controls a pool of worker processes,
+  The :class:`~multiprocessing.Pool` class, which controls a pool of worker processes,
   now has an optional *maxtasksperchild* parameter.  Worker processes
   will perform the specified number of tasks and then exit, causing the
-  :class:`Pool` to start a new worker.  This is useful if tasks may leak
+  :class:`~multiprocessing.Pool` to start a new worker.  This is useful if tasks may leak
   memory or other resources, or if some tasks will cause the worker to
   become very large.
   (Contributed by Charles Cazabon; :issue:`6963`.)
@@ -794,47 +850,50 @@ changes, or look through the Subversion logs for all the details.
   (Contributed by Derek Morr; :issue:`1664`.)
 
 * New functions: the :mod:`os` module wraps the following POSIX system
-  calls: :func:`getresgid` and :func:`getresuid`, which return the
+  calls: :func:`~os.getresgid` and :func:`~os.getresuid`, which return the
   real, effective, and saved GIDs and UIDs;
-  :func:`setresgid` and :func:`setresuid`, which set
+  :func:`~os.setresgid` and :func:`~os.setresuid`, which set
   real, effective, and saved GIDs and UIDs to new values;
-  :func:`initgroups`.  (GID/UID functions
+  :func:`~os.initgroups`.  (GID/UID functions
   contributed by Travis H.; :issue:`6508`.  Support for initgroups added
   by Jean-Paul Calderone; :issue:`7333`.)
 
   The :func:`os.fork` function now re-initializes the import lock in
-  the child process; this fixes problems on Solaris when :func:`fork`
+  the child process; this fixes problems on Solaris when :func:`~os.fork`
   is called from a thread.  (Fixed by Zsolt Cserna; :issue:`7242`.)
 
-  The :func:`normpath` function now preserves Unicode; if its input path
+* In the :mod:`os.path` module, the :func:`~os.path.normpath` and
+  :func:`~os.path.abspath` functions now preserve Unicode; if their input path
   is a Unicode string, the return value is also a Unicode string.
-  (Fixed by Matt Giuca; :issue:`5827`.)
+  (:meth:`~os.path.normpath` fixed by Matt Giuca in :issue:`5827`;
+  :meth:`~os.path.abspath` fixed by Ezio Melotti in :issue:`3426`.)
 
 * The :mod:`pydoc` module now has help for the various symbols that Python
   uses.  You can now do ``help('<<')`` or ``help('@')``, for example.
   (Contributed by David Laban; :issue:`4739`.)
 
-* The :mod:`re` module's :func:`split`, :func:`sub`, and :func:`subn`
+* The :mod:`re` module's :func:`~re.split`, :func:`~re.sub`, and :func:`~re.subn`
   now accept an optional *flags* argument, for consistency with the
   other functions in the module.  (Added by Gregory P. Smith.)
 
-* The :mod:`shutil` module's :func:`copyfile` and :func:`copytree`
-  functions now raises a :exc:`SpecialFileError` exception when
+* New function: in the :mod:`shutil` module, :func:`~shutil.make_archive`
+  takes a filename, archive type (zip or tar-format), and a directory
+  path, and creates an archive containing the directory's contents.
+  (Added by Tarek Ziadé.)
+
+  :mod:`shutil`'s :func:`~shutil.copyfile` and :func:`~shutil.copytree`
+  functions now raise a :exc:`~shutil.SpecialFileError` exception when
   asked to copy a named pipe.  Previously the code would treat
   named pipes like a regular file by opening them for reading, and
   this would block indefinitely.  (Fixed by Antoine Pitrou; :issue:`3002`.)
 
-  New function: :func:`make_archive` takes a filename, archive type
-  (zip or tar-format), and a directory path, and creates an archive
-  containing the directory's contents.  (Added by Tarek Ziadé.)
-
 * New functions: in the :mod:`site` module, three new functions
   return various site- and user-specific paths.
-  :func:`getsitepackages` returns a list containing all
+  :func:`~site.getsitepackages` returns a list containing all
   global site-packages directories, and
-  :func:`getusersitepackages` returns the path of the user's
+  :func:`~site.getusersitepackages` returns the path of the user's
   site-packages directory.
-  :func:`getuserbase` returns the value of the :envvar:`USER_BASE`
+  :func:`~site.getuserbase` returns the value of the :envvar:`USER_BASE`
   environment variable, giving the path to a directory that can be used
   to store data.
   (Contributed by Tarek Ziadé; :issue:`6693`.)
@@ -844,32 +903,32 @@ changes, or look through the Subversion logs for all the details.
   catch and swallow the :exc:`KeyboardInterrupt` exception.  (Fixed by
   Victor Stinner; :issue:`3137`.)
 
-* The :mod:`socket` module's :class:`SSL` objects now support the
+* The :mod:`socket` module's :class:`~ssl.SSL` objects now support the
   buffer API, which fixed a test suite failure.  (Fixed by Antoine
   Pitrou; :issue:`7133`.)
 
-  The :func:`create_connection` function
+  The :func:`~socket.create_connection` function
   gained a *source_address* parameter, a ``(host, port)`` 2-tuple
   giving the source address that will be used for the connection.
   (Contributed by Eldon Ziegler; :issue:`3972`.)
 
-  The :meth:`recv_into` and :meth:`recvfrom_into` methods will now write
-  into objects that support the buffer API, most usefully
+  The :meth:`~socket.socket.recv_into` and :meth:`~socket.socket.recvfrom_into`
+  methods will now write into objects that support the buffer API, most usefully
   the :class:`bytearray` and :class:`memoryview` objects.  (Implemented by
   Antoine Pitrou; :issue:`8104`.)
 
-* The :mod:`SocketServer` module's :class:`TCPServer` class now
-  has a :attr:`disable_nagle_algorithm` class attribute.
+* The :mod:`SocketServer` module's :class:`~SocketServer.TCPServer` class now
+  has a :attr:`~SocketServer.TCPServer.disable_nagle_algorithm` class attribute.
   The default value is False; if overridden to be True,
   new request connections will have the TCP_NODELAY option set to
   prevent buffering many small sends into a single TCP packet.
   (Contributed by Kristjan Valur Jonsson; :issue:`6192`.)
 
-* Updated module: the :mod:`sqlite` module has been updated to
+* Updated module: the :mod:`sqlite3` module has been updated to
   version 2.6.0 of the `pysqlite package <http://code.google.com/p/pysqlite/>`__. Version 2.6.0 includes a number of bugfixes, and adds
   the ability to load SQLite extensions from shared libraries.
   Call the ``enable_load_extension(True)`` method to enable extensions,
-  and then call :meth:`load_extension` to load a particular shared library.
+  and then call :meth:`~sqlite3.Connection.load_extension` to load a particular shared library.
   (Updated by Gerhard Häring.)
 
 * The :mod:`struct` module will no longer silently ignore overflow
@@ -879,9 +938,9 @@ changes, or look through the Subversion logs for all the details.
   :issue:`1523`.)
 
 * New function: the :mod:`subprocess` module's
-  :func:`check_output` runs a command with a specified set of arguments
+  :func:`~subprocess.check_output` runs a command with a specified set of arguments
   and returns the command's output as a string when the command runs without
-  error, or raises a :exc:`CalledProcessError` exception otherwise.
+  error, or raises a :exc:`~subprocess.CalledProcessError` exception otherwise.
 
   ::
 
@@ -895,7 +954,11 @@ changes, or look through the Subversion logs for all the details.
 
   (Contributed by Gregory P. Smith.)
 
-* New function: :func:`is_declared_global` in the :mod:`symtable` module
+  The :mod:`subprocess` module will now retry its internal system calls
+  on receiving an :const:`EINTR` signal.  (Reported by several people; final
+  patch by Gregory P. Smith in :issue:`1068268`.)
+
+* New function: :func:`~symtable.is_declared_global` in the :mod:`symtable` module
   returns true for variables that are explicitly declared to be global,
   false for ones that are implicitly global.
   (Contributed by Jeremy Hylton.)
@@ -919,65 +982,61 @@ changes, or look through the Subversion logs for all the details.
   which raises an exception if there's an error.
   (Changed by Lars Gustäbel; :issue:`7357`.)
 
-  :mod:`tarfile` now supports filtering the :class:`TarInfo`
-  objects being added to a tar file.  When you call :meth:`TarFile.add`,
+  :mod:`tarfile` now supports filtering the :class:`~tarfile.TarInfo`
+  objects being added to a tar file.  When you call :meth:`~tarfile.TarFile.add`,
   instance, you may supply an optional *filter* argument
   that's a callable.  The *filter* callable will be passed the
-  :class:`TarInfo` for every file being added, and can modify and return it.
+  :class:`~tarfile.TarInfo` for every file being added, and can modify and return it.
   If the callable returns ``None``, the file will be excluded from the
   resulting archive.  This is more powerful than the existing
   *exclude* argument, which has therefore been deprecated.
   (Added by Lars Gustäbel; :issue:`6856`.)
-  The :class:`TarFile` class also now supports the context manager protocol.
+  The :class:`~tarfile.TarFile` class also now supports the context manager protocol.
   (Added by Lars Gustäbel; :issue:`7232`.)
 
-* The :mod:`threading` module's :meth:`Event.wait` method now returns
-  the internal flag on exit.  This means the method will usually
-  return true because :meth:`wait` is supposed to block until the
+* The :meth:`~threading.Event.wait` method of the :class:`threading.Event` class
+  now returns the internal flag on exit.  This means the method will usually
+  return true because :meth:`~threading.Event.wait` is supposed to block until the
   internal flag becomes true.  The return value will only be false if
   a timeout was provided and the operation timed out.
   (Contributed by Tim Lesher; :issue:`1674032`.)
 
-* The Unicode database has been updated to the version 5.2.0.
-  (Updated by Florent Xicluna; :issue:`8024`.)
-
-* The Unicode database provided by the :mod:`unicodedata` is used
-  internally to determine which characters are numeric, whitespace,
-  or represent line breaks.  The database also now includes information
-  from the :file:`Unihan.txt` data file.  (Patch by Anders Chrigström
-  and Amaury Forgeot d'Arc; :issue:`1571184`.)
+* The Unicode database provided by the :mod:`unicodedata` module is
+  now used internally to determine which characters are numeric,
+  whitespace, or represent line breaks.  The database also
+  includes information from the :file:`Unihan.txt` data file (patch
+  by Anders Chrigström and Amaury Forgeot d'Arc; :issue:`1571184`)
+  and has been updated to version 5.2.0 (updated by
+  Florent Xicluna; :issue:`8024`).
 
-* The :class:`UserDict` class is now a new-style class.  (Changed by
+* The :class:`~UserDict.UserDict` class is now a new-style class.  (Changed by
   Benjamin Peterson.)
 
 * The ElementTree library, :mod:`xml.etree`, no longer escapes
   ampersands and angle brackets when outputting an XML processing
-  instruction (which looks like `<?xml-stylesheet href="#style1"?>`)
-  or comment (which looks like `<!-- comment -->`).
+  instruction (which looks like ``<?xml-stylesheet href="#style1"?>``)
+  or comment (which looks like ``<!-- comment -->``).
   (Patch by Neil Muller; :issue:`2746`.)
 
-* The :mod:`zipfile` module's :class:`ZipFile` now supports the context
+* The :mod:`zipfile` module's :class:`~zipfile.ZipFile` now supports the context
   management protocol, so you can write ``with zipfile.ZipFile(...) as f: ...``.
   (Contributed by Brian Curtin; :issue:`5511`.)
 
   :mod:`zipfile` now supports archiving empty directories and
   extracts them correctly.  (Fixed by Kuba Wieczorek; :issue:`4710`.)
   Reading files out of an archive is now faster, and interleaving
-  :meth:`read` and :meth:`readline` now works correctly.
+  :meth:`~zipfile.ZipFile.read` and :meth:`~zipfile.ZipFile.readline` now works correctly.
   (Contributed by Nir Aides; :issue:`7610`.)
 
-  The :func:`is_zipfile` function in the module now
+  The :func:`~zipfile.is_zipfile` function now
   accepts a file object, in addition to the path names accepted in earlier
   versions.  (Contributed by Gabriel Genellina; :issue:`4756`.)
 
-  The :meth:`writestr` method now has an optional *compress_type* parameter
+  The :meth:`~zipfile.ZipFile.writestr` method now has an optional *compress_type* parameter
   that lets you override the default compression method specified in the
-  :class:`ZipFile` constructor.  (Contributed by Ronald Oussoren;
+  :class:`~zipfile.ZipFile` constructor.  (Contributed by Ronald Oussoren;
   :issue:`6003`.)
 
-* XXX the :mod:`shutil` module has now a :func:`make_archive` function
-  (see the module doc, contributed by Tarek)
-
 
 New module: sysconfig
 ---------------------------------
@@ -1001,6 +1060,9 @@ XXX write this.
 Distutils Enhancements
 ---------------------------------
 
+XXX all of this work has been moved to Distutils2
+XXX Not sure what we should say here
+
 Distutils is being more actively developed, thanks to Tarek Ziadé
 who has taken over maintenance of the package, so there are a number
 of fixes and improvements.
@@ -1054,111 +1116,135 @@ The :mod:`unittest` module was enhanced in several ways.
 The progress messages now shows 'x' for expected failures
 and 'u' for unexpected successes when run in verbose mode.
 (Contributed by Benjamin Peterson.)
-Test cases can raise the :exc:`SkipTest` exception to skip a test.
+Test cases can raise the :exc:`~unittest.SkipTest` exception to skip a test.
 (:issue:`1034053`.)
 
 .. XXX describe test discovery (Contributed by Michael Foord; :issue:`6001`.)
 
-The error messages for :meth:`assertEqual`,
-:meth:`assertTrue`, and :meth:`assertFalse`
+The error messages for :meth:`~unittest.TestCase.assertEqual`,
+:meth:`~unittest.TestCase.assertTrue`, and :meth:`~unittest.TestCase.assertFalse`
 failures now provide more information.  If you set the
-:attr:`longMessage` attribute of your :class:`TestCase` classes to
-true, both the standard error message and any additional message you
+:attr:`~unittest.TestCase.longMessage` attribute of your :class:`~unittest.TestCase` classes to
+True, both the standard error message and any additional message you
 provide will be printed for failures.  (Added by Michael Foord; :issue:`5663`.)
 
-The :meth:`assertRaises` and :meth:`failUnlessRaises` methods now
+The :meth:`~unittest.TestCase.assertRaises` method now
 return a context handler when called without providing a callable
 object to run.  For example, you can write this::
 
   with self.assertRaises(KeyError):
-      raise ValueError
+      {}['foo']
 
 (Implemented by Antoine Pitrou; :issue:`4444`.)
 
-The methods :meth:`addCleanup` and :meth:`doCleanups` were added.
-:meth:`addCleanup` allows you to add cleanup functions that
-will be called unconditionally (after :meth:`setUp` if
-:meth:`setUp` fails, otherwise after :meth:`tearDown`). This allows
-for much simpler resource allocation and deallocation during tests.
-:issue:`5679`
+.. rev 78774
+
+Module- and class-level setup and teardown fixtures are now supported.
+Modules can contain :func:`~unittest.setUpModule` and :func:`~unittest.tearDownModule`
+functions.  Classes can have :meth:`~unittest.TestCase.setUpClass` and
+:meth:`~unittest.TestCase.tearDownClass` methods that must be defined as class methods
+(using ``@classmethod`` or equivalent).  These functions and
+methods are invoked when the test runner switches to a test case in a
+different module or class.
+
+The methods :meth:`~unittest.TestCase.addCleanup` and
+:meth:`~unittest.TestCase.doCleanups` were added.
+:meth:`~unittest.TestCase.addCleanup` allows you to add cleanup functions that
+will be called unconditionally (after :meth:`~unittest.TestCase.setUp` if
+:meth:`~unittest.TestCase.setUp` fails, otherwise after :meth:`~unittest.TestCase.tearDown`). This allows
+for much simpler resource allocation and deallocation during tests
+(:issue:`5679`).
 
 A number of new methods were added that provide more specialized
 tests.  Many of these methods were written by Google engineers
 for use in their test suites; Gregory P. Smith, Michael Foord, and
 GvR worked on merging them into Python's version of :mod:`unittest`.
 
-* :meth:`assertIsNone` and :meth:`assertIsNotNone` take one
+* :meth:`~unittest.TestCase.assertIsNone` and :meth:`~unittest.TestCase.assertIsNotNone` take one
   expression and verify that the result is or is not ``None``.
 
-* :meth:`assertIs` and :meth:`assertIsNot` take two values and check
-  whether the two values evaluate to the same object or not.
+* :meth:`~unittest.TestCase.assertIs` and :meth:`~unittest.TestCase.assertIsNot`
+  take two values and check whether the two values evaluate to the same object or not.
   (Added by Michael Foord; :issue:`2578`.)
 
-* :meth:`assertIsInstance` and :meth:`assertNotIsInstance` check whether
+* :meth:`~unittest.TestCase.assertIsInstance` and
+  :meth:`~unittest.TestCase.assertNotIsInstance` check whether
   the resulting object is an instance of a particular class, or of
   one of a tuple of classes.  (Added by Georg Brandl; :issue:`7031`.)
 
-* :meth:`assertGreater`, :meth:`assertGreaterEqual`,
-  :meth:`assertLess`, and :meth:`assertLessEqual` compare
+* :meth:`~unittest.TestCase.assertGreater`, :meth:`~unittest.TestCase.assertGreaterEqual`,
+  :meth:`~unittest.TestCase.assertLess`, and :meth:`~unittest.TestCase.assertLessEqual` compare
   two quantities.
 
-* :meth:`assertMultiLineEqual` compares two strings, and if they're
+* :meth:`~unittest.TestCase.assertMultiLineEqual` compares two strings, and if they're
   not equal, displays a helpful comparison that highlights the
   differences in the two strings.  This comparison is now used by
-  default when Unicode strings are compared with :meth:`assertEqual`.)
+  default when Unicode strings are compared with :meth:`~unittest.TestCase.assertEqual`.
 
-* :meth:`assertRegexpMatches` checks whether its first argument is a
+* :meth:`~unittest.TestCase.assertRegexpMatches` checks whether its first argument is a
   string matching a regular expression provided as its second argument.
 
-* :meth:`assertRaisesRegexp` checks whether a particular exception
+  .. XXX add assertNotRegexpMatches see issue 8038
+
+* :meth:`~unittest.TestCase.assertRaisesRegexp` checks whether a particular exception
   is raised, and then also checks that the string representation of
   the exception matches the provided regular expression.
 
-* :meth:`assertIn` and :meth:`assertNotIn` tests whether
-  *first* is or is not in  *second*.
+* :meth:`~unittest.TestCase.assertIn` and :meth:`~unittest.TestCase.assertNotIn`
+  tests whether *first* is or is not in  *second*.
 
-* :meth:`assertItemsEqual` tests whether two provided sequences
+* :meth:`~unittest.TestCase.assertItemsEqual` tests whether two provided sequences
   contain the same elements.
 
-* :meth:`assertSetEqual` compares whether two sets are equal, and
+* :meth:`~unittest.TestCase.assertSetEqual` compares whether two sets are equal, and
   only reports the differences between the sets in case of error.
 
-* Similarly, :meth:`assertListEqual` and :meth:`assertTupleEqual`
+* Similarly, :meth:`~unittest.TestCase.assertListEqual` and :meth:`~unittest.TestCase.assertTupleEqual`
   compare the specified types and explain any differences without necessarily
   printing their full values; these methods are now used by default
-  when comparing lists and tuples using :meth:`assertEqual`.
-  More generally, :meth:`assertSequenceEqual` compares two sequences
+  when comparing lists and tuples using :meth:`~unittest.TestCase.assertEqual`.
+  More generally, :meth:`~unittest.TestCase.assertSequenceEqual` compares two sequences
   and can optionally check whether both sequences are of a
   particular type.
 
-* :meth:`assertDictEqual` compares two dictionaries and reports the
+* :meth:`~unittest.TestCase.assertDictEqual` compares two dictionaries and reports the
   differences; it's now used by default when you compare two dictionaries
-  using :meth:`assertEqual`.  :meth:`assertDictContainsSubset` checks whether
+  using :meth:`~unittest.TestCase.assertEqual`.  :meth:`~unittest.TestCase.assertDictContainsSubset` checks whether
   all of the key/value pairs in *first* are found in *second*.
 
-* :meth:`assertAlmostEqual` and :meth:`assertNotAlmostEqual` test
+* :meth:`~unittest.TestCase.assertAlmostEqual` and :meth:`~unittest.TestCase.assertNotAlmostEqual` test
   whether *first* and *second* are approximately equal by computing
   their difference, rounding the result to an optionally-specified number
   of *places* (the default is 7), and comparing to zero.
 
-* :meth:`loadTestsFromName` properly honors the ``suiteClass`` attribute of
-  the :class:`TestLoader`. (Fixed by Mark Roddy; :issue:`6866`.)
+* :meth:`~unittest.TestLoader.loadTestsFromName` properly honors the
+  :attr:`~unittest.TestLoader.suiteClass` attribute of
+  the :class:`~unittest.TestLoader`. (Fixed by Mark Roddy; :issue:`6866`.)
+
+* A new hook lets you extend the :meth:`~unittest.TestCase.assertEqual` method to handle
+  new data types.  The :meth:`~unittest.TestCase.addTypeEqualityFunc` method takes a type
+  object and a function. The function will be used when both of the
+  objects being compared are of the specified type.  This function
+  should compare the two objects and raise an exception if they don't
+  match; it's a good idea for the function to provide additional
+  information about why the two objects are matching, much as the new
+  sequence comparison methods do.
+
+:func:`unittest.main` now takes an optional ``exit`` argument.  If
+False, :func:`~unittest.main` doesn't call :func:`sys.exit`, allowing it to be
+used from the interactive interpreter. (Contributed by J. Pablo
+Fernández; :issue:`3379`.)
 
-* A new hook, :meth:`addTypeEqualityFunc` takes a type object and a
-  function.  The :meth:`assertEqual` method will use the function
-  when both of the objects being compared are of the specified type.
-  This function should compare the two objects and raise an
-  exception if they don't match; it's a good idea for the function
-  to provide additional information about why the two objects are
-  matching, much as the new sequence comparison methods do.
+A new command-line switch, :option:`-f` or :option:`--failfast`, makes
+test execution stop immediately when a test fails instead of
+continuing to execute further tests.  (Suggested by Cliff Dyer and
+implemented by Michael Foord; :issue:`8074`.)
 
-:func:`unittest.main` now takes an optional ``exit`` argument.
-If False ``main`` doesn't call :func:`sys.exit` allowing it to
-be used from the interactive interpreter. :issue:`3379`.
+.. XXX document the other new switches
 
-:class:`TestResult` has new :meth:`startTestRun` and
-:meth:`stopTestRun` methods; called immediately before
-and after a test run. :issue:`5728` by Robert Collins.
+:class:`~unittest.TestResult` has new :meth:`~unittest.TestResult.startTestRun` and
+:meth:`~unittest.TestResult.stopTestRun` methods that are called immediately before
+and after a test run.  (Contributed by Robert Collins; :issue:`5728`.)
 
 With all these changes, the :file:`unittest.py` was becoming awkwardly
 large, so the module was turned into a package and the code split into
@@ -1177,7 +1263,7 @@ of the logic underlying Python's :keyword:`import` statement.
 to users who wish to write new importers that can participate in the
 import process.  Python 2.7 doesn't contain the complete
 :mod:`importlib` package, but instead has a tiny subset that contains
-a single function, :func:`import_module`.
+a single function, :func:`~importlib.import_module`.
 
 ``import_module(name, package=None)`` imports a module.  *name* is
 a string containing the module or package's name.  It's possible to do
@@ -1185,7 +1271,7 @@ relative imports by providing a string that begins with a ``.``
 character, such as ``..utils.errors``.  For relative imports, the
 *package* argument must be provided and is the name of the package that
 will be used as the anchor for
-the relative import.  :func:`import_module` both inserts the imported
+the relative import.  :func:`~importlib.import_module` both inserts the imported
 module into ``sys.modules`` and returns the module object.
 
 Here are some examples::