merge

5 files changed, 204 insertions, 63 deletions

diff --git a/Doc/distutils/uploading.rst b/Doc/distutils/uploading.rst
index dc1025f..bfb392e 100644
--- a/Doc/distutils/uploading.rst
+++ b/Doc/distutils/uploading.rst
@@ -74,5 +74,7 @@ check the ``long_description`` from the command line::
 
 :mod:`docutils` will display a warning if there's something wrong with your
 syntax.  Because PyPI applies additional checks (e.g. by passing ``--no-raw``
-to ``rst2html.py`` in the command above), running the command above without
-warnings is not sufficient for PyPI to convert the content successfully.
+to ``rst2html.py`` in the command above), being able to run the command above
+without warnings does not guarantee that PyPI will convert the content
+successfully.
+
diff --git a/Doc/howto/ipaddress.rst b/Doc/howto/ipaddress.rst
index 6680d65..1b6d05c 100644
--- a/Doc/howto/ipaddress.rst
+++ b/Doc/howto/ipaddress.rst
@@ -19,7 +19,7 @@ An Introduction to the ipaddress module
 Creating Address/Network/Interface objects
 ==========================================
 
-Since :mod:`ipaddress` is a module for inspecting and manipulating IP address,
+Since :mod:`ipaddress` is a module for inspecting and manipulating IP addresses,
 the first thing you'll want to do is create some objects.  You can use
 :mod:`ipaddress` to create objects from strings and integers.
 
@@ -183,10 +183,10 @@ Finding out how many individual addresses are in a network::
    >>> net6.numhosts
    4294967296
 
-Iterating through the 'usable' addresses on a network::
+Iterating through the "usable" addresses on a network::
 
    >>> net4 = ipaddress.ip_network('192.0.2.0/24')
-   >>> for x in net4.iterhosts():
+   >>> for x in net4.hosts():
           print(x)
    192.0.2.1
    192.0.2.2
@@ -294,7 +294,7 @@ Getting more detail when instance creation fails
 When creating address/network/interface objects using the version-agnostic
 factory functions, any errors will be reported as :exc:`ValueError` with
 a generic error message that simply says the passed in value was not
-recognised as an object of that type. The lack of a specific error is
+recognized as an object of that type. The lack of a specific error is
 because it's necessary to know whether the value is *supposed* to be IPv4
 or IPv6 in order to provide more detail on why it has been rejected.
 
diff --git a/Doc/library/faulthandler.rst b/Doc/library/faulthandler.rst
index c9b9546..b079b30 100644
--- a/Doc/library/faulthandler.rst
+++ b/Doc/library/faulthandler.rst
@@ -23,7 +23,7 @@ tracebacks:
 
 * Only ASCII is supported. The ``backslashreplace`` error handler is used on
   encoding.
-* Each string is limited to 100 characters.
+* Each string is limited to 500 characters.
 * Only the filename, the function name and the line number are
   displayed. (no source code)
 * It is limited to 100 frames and 100 threads.
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 1cbe34a..0bb22aa 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1506,6 +1506,9 @@ are always available.  They are listed here in alphabetical order.
    If you simply want to import a module (potentially within a package) by name,
    use :func:`importlib.import_module`.
 
+   .. versionchanged:: 3.3
+      Negative values for *level* are no longer supported.
+
 
 .. rubric:: Footnotes
 
diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst
index b4cbb2c..e9af9c5 100644
--- a/Doc/library/ipaddress.rst
+++ b/Doc/library/ipaddress.rst
@@ -22,19 +22,18 @@ subnet, as well as checking whether or not a string represents a valid
 IP address or network definition.
 
 
-Defining IP Addresses and Interfaces
-------------------------------------
+Convenience factory functions
+-----------------------------
 
-The :mod:`ipaddress` module provides factory functions to define IP addresses
-and networks:
+The :mod:`ipaddress` module provides factory functions to conveniently create
+IP addresses, networks and interfaces:
 
 .. function:: ip_address(address)
 
    Return an :class:`IPv4Address` or :class:`IPv6Address` object depending on
-   the IP address passed as argument.  *address* is a string or integer
-   representing the IP address.  Either IPv4 or IPv6 addresses may be supplied;
-   integers less than 2**32 will be considered to be IPv4 by default.  A
-   :exc:`ValueError` is raised if the *address* passed is neither an IPv4 nor
+   the IP address passed as argument.  Either IPv4 or IPv6 addresses may be
+   supplied; integers less than 2**32 will be considered to be IPv4 by default.
+   A :exc:`ValueError` is raised if *address* does not represent a valid IPv4 or
    IPv6 address.
 
    >>> ipaddress.ip_address('192.168.0.1')
@@ -50,8 +49,8 @@ and networks:
    representing the IP network.  Either IPv4 or IPv6 networks may be supplied;
    integers less than 2**32 will be considered to be IPv4 by default.  *strict*
    is passed to :class:`IPv4Network` or :class:`IPv6Network` constructor.  A
-   :exc:`ValueError` is raised if the string passed isn't either an IPv4 or IPv6
-   address, or if the network has host bits set.
+   :exc:`ValueError` is raised if *address* does not represent a valid IPv4 or
+   IPv6 address, or if the network has host bits set.
 
    >>> ipaddress.ip_network('192.168.0.0/28')
    IPv4Network('192.168.0.0/28')
@@ -62,45 +61,174 @@ and networks:
    Return an :class:`IPv4Interface` or :class:`IPv6Interface` object depending
    on the IP address passed as argument.  *address* is a string or integer
    representing the IP address.  Either IPv4 or IPv6 addresses may be supplied;
-   integers less than 2**32 will be considered to be IPv4 by default..  A
-   :exc:`ValueError` is raised if the *address* passed isn't either an IPv4 or
+   integers less than 2**32 will be considered to be IPv4 by default.  A
+   :exc:`ValueError` is raised if *address* does not represent a valid IPv4 or
    IPv6 address.
 
 
-Representing IP Addresses and Networks
---------------------------------------
+Address objects
+---------------
 
-The module defines the following and classes to represent IP addresses
-and networks:
-
-.. todo: list the properties and methods
+The :class:`IPv4Address` and :class:`IPv6Address` objects share a lot of common
+attributes.  Some attributes that are only meaningful for IPv6 addresses are
+also implemented by :class:`IPv4Address` objects, in order to make it easier to
+write code that handles both IP versions correctly.  To avoid duplication, all
+common attributes will only be documented for :class:`IPv4Address`.
 
 .. class:: IPv4Address(address)
 
-   Construct an IPv4 address.  *address* is a string or integer representing the
-   IP address.  An :exc:`AddressValueError` is raised if *address* is not a
-   valid IPv4 address.
+   Construct an IPv4 address.  An :exc:`AddressValueError` is raised if
+   *address* is not a valid IPv4 address.
+
+   The following constitutes a valid IPv4 address:
+
+   1. A string in decimal-dot notation, consisting of four decimal integers in
+      the inclusive range 0-255, separated by dots (e.g. ``192.168.0.1``). Each
+      integer represents an octet (byte) in the address, big-endian.
+   2. An integer that fits into 32 bits.
+   3. An integer packed into a :class:`bytes` object of length 4, big-endian.
 
    >>> ipaddress.IPv4Address('192.168.0.1')
    IPv4Address('192.168.0.1')
    >>> ipaddress.IPv4Address('192.0.2.1') == ipaddress.IPv4Address(3221225985)
    True
 
+   .. attribute:: exploded
 
-.. class:: IPv4Interface(address)
+   The longhand version of the address as a string. Note: the
+   exploded/compressed distinction is meaningful only for IPv6 addresses.
+   For IPv4 addresses it is the same.
 
-   Construct an IPv4 interface.  *address* is a string or integer representing
-   the IP interface.  An :exc:`AddressValueError` is raised if *address* is not
-   a valid IPv4 address.
+   .. attribute:: compressed
 
-   The network address for the interface is determined by calling
-   ``IPv4Network(address, strict=False)``.
+   The shorthand version of the address as a string.
 
-   >>> ipaddress.IPv4Interface('192.168.0.0/24')
-   IPv4Interface('192.168.0.0/24')
-   >>> ipaddress.IPv4Interface('192.168.0.0/24').network
-   IPv4Network('192.168.0.0/24')
+   .. attribute:: packed
+
+   The binary representation of this address - a :class:`bytes` object.
+
+   .. attribute:: version
+
+   A numeric version number.
+
+   .. attribute:: max_prefixlen
+
+   Maximal length of the prefix (in bits).  The prefix defines the number of
+   leading bits in an address that are compared to determine whether or not an
+   address is part of a network.
+
+   .. attribute:: is_multicast
+
+   ``True`` if the address is reserved for multicast use.  See :RFC:`3171` (for
+   IPv4) or :RFC:`2373` (for IPv6).
+
+   .. attribute:: is_private
+
+   ``True`` if the address is allocated for private networks.  See :RFC:`1918`
+   (for IPv4) or :RFC:`4193` (for IPv6).
+
+   .. attribute:: is_unspecified
+
+   ``True`` if the address is unspecified.  See :RFC:`5375` (for IPv4) or
+   :RFC:`2373` (for IPv6).
+
+   .. attribute:: is_reserved
+
+   ``True`` if the address is otherwise IETF reserved.
+
+   .. attribute:: is_loopback
+
+   ``True`` if this is a loopback address.  See :RFC:`3330` (for IPv4) or
+   :RFC:`2373` (for IPv6).
+
+   .. attribute:: is_link_local
+
+   ``True`` if the address is reserved for link-local.  See :RFC:`3927`.
+
+.. class:: IPv6Address(address)
+
+   Construct an IPv6 address.  An :exc:`AddressValueError` is raised if
+   *address* is not a valid IPv6 address.
+
+   The following constitutes a valid IPv6 address:
+
+   1. A string consisting of eight groups of four hexadecimal digits, each
+      group representing 16 bits.  The groups are separated by colons.
+      This describes an *exploded* (longhand) notation.  The string can
+      also be *compressed* (shorthand notation) by various means.  See
+      :RFC:`4291` for details.  For example,
+      ``"0000:0000:0000:0000:0000:0abc:0007:0def"`` can be compressed to
+      ``"::abc:7:def"``.
+   2. An integer that fits into 128 bits.
+   3. An integer packed into a :class:`bytes` object of length 16, big-endian.
+
+   >>> ipaddress.IPv6Address('2001:db8::1000')
+   IPv6Address('2001:db8::1000')
+
+   All the attributes exposed by :class:`IPv4Address` are supported.  In
+   addition, the following attributs are exposed only by :class:`IPv6Address`.
+
+   .. attribute:: is_site_local
+
+   ``True`` if the address is reserved for site-local.  Note that the site-local
+   address space has been deprecated by :RFC:`3879`.  Use
+   :attr:`~IPv4Address.is_private` to test if this address is in the space of
+   unique local addresses as defined by :RFC:`4193`.
+
+   .. attribute:: ipv4_mapped
+
+   If this address represents a IPv4 mapped address, return the IPv4 mapped
+   address.  Otherwise return ``None``.
+
+   .. attribute:: teredo
+
+   If this address appears to be a teredo address (starts with ``2001::/32``),
+   return a tuple of embedded teredo IPs ``(server, client)`` pairs.  Otherwise
+   return ``None``.
+
+   .. attribute:: sixtofour
+
+   If this address appears to contain a 6to4 embedded address, return the
+   embedded IPv4 address.  Otherwise return ``None``.
+
+
+Operators
+^^^^^^^^^
+
+Address objects support some operators.  Unless stated otherwise, operators can
+only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
+IPv6).
+
+Logical operators
+"""""""""""""""""
+
+Address objects can be compared with the usual set of logical operators.  Some
+examples::
+
+   >>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1')
+   True
+   >>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1')
+   False
+   >>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1')
+   True
 
+Arithmetic operators
+""""""""""""""""""""
+
+Integers can be added to or subtracted from address objects.  Some examples::
+
+   >>> IPv4Address('127.0.0.2') + 3
+   IPv4Address('127.0.0.5')
+   >>> IPv4Address('127.0.0.2') - 3
+   IPv4Address('126.255.255.255')
+   >>> IPv4Address('255.255.255.255') + 1
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in <module>
+   ipaddress.AddressValueError: 4294967296 (>= 2**32) is not permitted as an IPv4 address
+
+
+Network objects
+---------------
 
 .. class:: IPv4Network(address, strict=True)
 
@@ -121,31 +249,6 @@ and networks:
    IPv4Network('192.0.2.0/27')
 
 
-.. class:: IPv6Address(address)
-
-   Construct an IPv6 address.  *address* is a string or integer representing the
-   IP address.  An :exc:`AddressValueError` is raised if *address* is not a
-   valid IPv6 address.
-
-   >>> ipaddress.IPv6Address('2001:db8::1000')
-   IPv6Address('2001:db8::1000')
-
-
-.. class:: IPv6Interface(address)
-
-   Construct an IPv6 interface.  *address* is a string or integer representing
-   the IP interface.  An :exc:`AddressValueError` is raised if *address* is not
-   a valid IPv6 address.
-
-   The network address for the interface is determined by calling
-   ``IPv6Network(address, strict=False)``.
-
-   >>> ipaddress.IPv6Interface('2001:db8::1000/96')
-   IPv6Interface('2001:db8::1000/96')
-   >>> ipaddress.IPv6Interface('2001:db8::1000/96').network
-   IPv6Network('2001:db8::/96')
-
-
 .. class:: IPv6Network(address, strict=True)
 
    Construct an IPv6 network.  *address* is a string or integer representing the
@@ -165,6 +268,39 @@ and networks:
    IPv6Network('2001:db8::/96')
 
 
+Interface objects
+-----------------
+
+.. class:: IPv4Interface(address)
+
+   Construct an IPv4 interface.  *address* is a string or integer representing
+   the IP interface.  An :exc:`AddressValueError` is raised if *address* is not
+   a valid IPv4 address.
+
+   The network address for the interface is determined by calling
+   ``IPv4Network(address, strict=False)``.
+
+   >>> ipaddress.IPv4Interface('192.168.0.0/24')
+   IPv4Interface('192.168.0.0/24')
+   >>> ipaddress.IPv4Interface('192.168.0.0/24').network
+   IPv4Network('192.168.0.0/24')
+
+
+.. class:: IPv6Interface(address)
+
+   Construct an IPv6 interface.  *address* is a string or integer representing
+   the IP interface.  An :exc:`AddressValueError` is raised if *address* is not
+   a valid IPv6 address.
+
+   The network address for the interface is determined by calling
+   ``IPv6Network(address, strict=False)``.
+
+   >>> ipaddress.IPv6Interface('2001:db8::1000/96')
+   IPv6Interface('2001:db8::1000/96')
+   >>> ipaddress.IPv6Interface('2001:db8::1000/96').network
+   IPv6Network('2001:db8::/96')
+
+
 Other Module Level Functions
 ----------------------------