Move email section in with other modules. Fix markup.

Doc/whatsnew/3.2.rst

@@ -361,46 +361,6 @@ module::
       PEP written by Barry Warsaw.
 
 
-Email
-=====
-
-The usability of the :mod:`email` package in Python 3 has been mostly fixed by
-the extensive efforts of R. David Murray.  The problem was that emails are
-typically read and stored in the form of :class:`bytes` rather than :class:`str`
-text, and they may contain multiple encodings within a single email.  So, the
-email package had to be extended to parse and generate email messages in bytes
-format.
-
-* New functions :func:`~email.message_from_bytes` and
-  :func:`~email.message_from_binary_file`, and new classes
-  :class:`~email.parser.BytesFeedParser` and :class:`~email.parser.BytesParser`
-  allow binary message data to be parsed into model objects.
-
-* Given bytes input to the model, :meth:`~email.message.Message.get_payload`
-  will by default decode a message body that has a
-  :mailheader:`Content-Transfer-Encoding` of *8bit* using the charset
-  specified in the MIME headers and return the resulting string.
-
-* Given bytes input to the model, :class:`~email.generator.Generator` will
-  convert message bodies that have a :mailheader:`Content-Transfer-Encoding` of
-  *8bit* to instead have a *7bit* :mailheader:`Content-Transfer-Encoding`.
-
-* A new class :class:`~email.generator.BytesGenerator` produces bytes as output,
-  preserving any unchanged non-ASCII data that was present in the input used to
-  build the model, including message bodies with a
-  :mailheader:`Content-Transfer-Encoding` of *8bit*.
-
-* The :mod:`smtplib` :class:`~smtplib.SMTP` class now accepts a byte string
-  for the *msg* argument to the :meth:`~smtplib.SMTP.sendmail` method,
-  and a new method, :meth:`~smtplib.SMTP.send_message` accepts a
-  :class:`~email.message.Message` object and can optionally obtain the
-  *from_addr* and *to_addrs* addresses directly from the object.
-
-.. XXX Update before 3.2rc1 to reflect all of the latest work and add examples.
-
-  (Proposed and implemented by R. David Murray, :issue:`4661` and :issue:`10321`.)
-
-
 Other Language Changes
 ======================
 
@@ -555,6 +515,46 @@ Some smaller changes made to the core Python language are:
 New, Improved, and Deprecated Modules
 =====================================
 
+email
+-----
+
+The usability of the :mod:`email` package in Python 3 has been mostly fixed by
+the extensive efforts of R. David Murray.  The problem was that emails are
+typically read and stored in the form of :class:`bytes` rather than :class:`str`
+text, and they may contain multiple encodings within a single email.  So, the
+email package had to be extended to parse and generate email messages in bytes
+format.
+
+* New functions :func:`~email.message_from_bytes` and
+  :func:`~email.message_from_binary_file`, and new classes
+  :class:`~email.parser.BytesFeedParser` and :class:`~email.parser.BytesParser`
+  allow binary message data to be parsed into model objects.
+
+* Given bytes input to the model, :meth:`~email.message.Message.get_payload`
+  will by default decode a message body that has a
+  :mailheader:`Content-Transfer-Encoding` of *8bit* using the charset
+  specified in the MIME headers and return the resulting string.
+
+* Given bytes input to the model, :class:`~email.generator.Generator` will
+  convert message bodies that have a :mailheader:`Content-Transfer-Encoding` of
+  *8bit* to instead have a *7bit* :mailheader:`Content-Transfer-Encoding`.
+
+* A new class :class:`~email.generator.BytesGenerator` produces bytes as output,
+  preserving any unchanged non-ASCII data that was present in the input used to
+  build the model, including message bodies with a
+  :mailheader:`Content-Transfer-Encoding` of *8bit*.
+
+* The :mod:`smtplib` :class:`~smtplib.SMTP` class now accepts a byte string
+  for the *msg* argument to the :meth:`~smtplib.SMTP.sendmail` method,
+  and a new method, :meth:`~smtplib.SMTP.send_message` accepts a
+  :class:`~email.message.Message` object and can optionally obtain the
+  *from_addr* and *to_addrs* addresses directly from the object.
+
+.. XXX Update before 3.2rc1 to reflect all of the latest work and add examples.
+
+(Proposed and implemented by R. David Murray, :issue:`4661` and :issue:`10321`.)
+
+
 functools
 ---------
 
@@ -715,7 +715,7 @@ also grew auto-closing context managers::
 (Contributed by Tarek Ziadé and Giampaolo Rodolà in :issue:`4972`, and
 by Georg Brandl in :issue:`8046` and :issue:`1286`.)
 
-.. mention os.popen and subprocess.Popen auto-closing of fds
+.. XXX mention os.popen and subprocess.Popen auto-closing of fds
 
 gzip
 ----
@@ -764,13 +764,13 @@ sqlite3
 
 The :mod:`sqlite3` module has two new capabilities.
 
-* The :attr:`Connection.in_transit` attribute is true if there is an active
+* The :attr:`sqlite3.Connection.in_transit` attribute is true if there is an
-  transaction for uncommitted changes.
+  active transaction for uncommitted changes.
 
-* The :meth:`Connection.enable_load_extension` and
+* The :meth:`sqlite3.Connection.enable_load_extension` and
-  :meth:`Connection.load_extension` methods allows you to load SQLite extensions
+  :meth:`sqlite3.Connection.load_extension` methods allows you to load SQLite
-  from ".so" files.  One well-known extension is the fulltext-search extension
+  extensions from ".so" files.  One well-known extension is the fulltext-search
-  distributed with SQLite.
+  extension distributed with SQLite.
 
 (Contributed by R. David Murray and Shashwat Anand; :issue:`8845`.)
 
@@ -915,12 +915,11 @@ unittest
 random
 ------
 
-The integer methods in the :mod:`random` module now do a better job of
+The integer methods in the :mod:`random` module now do a better job of producing
-producing uniform distributions.  Previously, they used ``int(n*random())``
+uniform distributions.  Previously, they used ``int(n*random())`` which had a
-which had a slight bias whenever *n* was not a power of two.  The methods
+slight bias whenever *n* was not a power of two.  The functions and methods
-affected are :meth:`~random.Random.randrange`, :meth:`~random.Random.randint`,
+affected are :func:`~random.randrange`, :func:`~random.randint`,
-:meth:`~random.Random.choice`, :meth:`~random.Random.shuffle` and
+:func:`~random.choice`, :func:`~random.shuffle` and :func:`~random.sample`.
-:meth:`~random.Random.sample`.
 
 (Contributed by Raymond Hettinger; :issue:`9025`.)
 
@@ -958,10 +957,11 @@ cleanup of temporary directories:
 inspect
 -------
 
-* The :mod:`inspect` module has a new function :func:`getgenatorstate` to easily
+* The :mod:`inspect` module has a new function
-  identify the current state of a generator as one of ``GEN_CREATED``,
+  :func:`~inspect.getgeneratorstate` to easily identify the current state of a
-  ``GEN_RUNNING``, ``GEN_SUSPENDED`` or ``GEN_CLOSED``. (Contributed by Rodolpho
+  generator as one of ``GEN_CREATED``, ``GEN_RUNNING``, ``GEN_SUSPENDED`` or
-  Eckhardt and Nick Coghlan, :issue:`10220`.)
+  ``GEN_CLOSED``. (Contributed by Rodolpho Eckhardt and Nick Coghlan,
+  :issue:`10220`.)
 
 * To support lookups without the possibility of activating a dynamic attribute,
   the :mod:`inspect` module has a new function, :func:`~inspect.getattr_static`.