merge 3.3

Doc/howto/ipaddress.rst

@@ -1,7 +1,7 @@
 .. _ipaddress-howto:
 
 ***************************************
-An Introduction to the ipaddress module
+An introduction to the ipaddress module
 ***************************************
 
 :author: Peter Moody
@@ -47,7 +47,12 @@ Addresses, often referred to as "host addresses" are the most basic unit
 when working with IP addressing. The simplest way to create addresses is
 to use the :func:`ipaddress.ip_address` factory function, which automatically
 determines whether to create an IPv4 or IPv6 address based on the passed in
-value::
+value:
+
+.. testsetup::
+   >>> import ipaddress
+
+::
 
    >>> ipaddress.ip_address('192.0.2.1')
    IPv4Address('192.0.2.1')
@@ -142,7 +147,7 @@ address.
 
    >>> ipaddress.ip_interface('192.0.2.1/24')
    IPv4Interface('192.0.2.1/24')
-   >>> ipaddress.ip_network('2001:db8::1/96')
+   >>> ipaddress.ip_interface('2001:db8::1/96')
    IPv6Interface('2001:db8::1/96')
 
 Integer inputs are accepted (as with networks), and use of a particular IP
@@ -177,22 +182,22 @@ Obtaining the network from an interface::
 Finding out how many individual addresses are in a network::
 
    >>> net4 = ipaddress.ip_network('192.0.2.0/24')
-   >>> net4.numhosts
+   >>> net4.num_addresses
    256
    >>> net6 = ipaddress.ip_network('2001:db8::0/96')
-   >>> net6.numhosts
+   >>> net6.num_addresses
    4294967296
 
 Iterating through the "usable" addresses on a network::
 
    >>> net4 = ipaddress.ip_network('192.0.2.0/24')
    >>> for x in net4.hosts():
-          print(x)
+   ...     print(x)  # doctest: +ELLIPSIS
    192.0.2.1
    192.0.2.2
    192.0.2.3
    192.0.2.4
-   <snip>
+   ...
    192.0.2.252
    192.0.2.253
    192.0.2.254
@@ -216,9 +221,9 @@ the hostmask (any bits that are not part of the netmask):
 Exploding or compressing the address::
 
    >>> addr6.exploded
-   '2001:0db8:0000:0000:0000:0000:0000:0000'
+   '2001:0db8:0000:0000:0000:0000:0000:0001'
    >>> addr6.compressed
-   '2001:db8::'
+   '2001:db8::1'
    >>> net6.exploded
    '2001:0db8:0000:0000:0000:0000:0000:0000/96'
    >>> net6.compressed
@@ -241,9 +246,9 @@ to index them like this::
    >>> net4[-1]
    IPv4Address('192.0.2.255')
    >>> net6[1]
-   IPv6Address('2001::1')
+   IPv6Address('2001:db8::1')
    >>> net6[-1]
-   IPv6Address('2001::ffff:ffff')
+   IPv6Address('2001:db8::ffff:ffff')
 
 
 It also means that network objects lend themselves to using the list

Doc/library/ipaddress.rst

@@ -42,8 +42,15 @@ IP addresses, networks and interfaces:
    Return an :class:`IPv4Address` or :class:`IPv6Address` object depending on
    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
+   A :exc:`ValueError` is raised if *address* does not represent a valid IPv4
-   IPv6 address.
+   or IPv6 address.
+
+.. testsetup::
+   >>> import ipaddress
+   >>> from ipaddress import (ip_network, IPv4Address, IPv4Interface,
+   ...                        IPv4Network)
+
+::
 
    >>> ipaddress.ip_address('192.168.0.1')
    IPv4Address('192.168.0.1')
@@ -111,7 +118,7 @@ write code that handles both IP versions correctly.
 
    >>> ipaddress.IPv4Address('192.168.0.1')
    IPv4Address('192.168.0.1')
-   >>> ipaddress.IPv4Address(3221225985)
+   >>> ipaddress.IPv4Address(3232235521)
    IPv4Address('192.168.0.1')
    >>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01')
    IPv4Address('192.168.0.1')
@@ -437,7 +444,7 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
       hosts are all the IP addresses that belong to the network, except the
       network address itself and the network broadcast address.
 
-         >>> list(ip_network('192.0.2.0/29').hosts())
+         >>> list(ip_network('192.0.2.0/29').hosts())  #doctest: +NORMALIZE_WHITESPACE
          [IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'),
           IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'),
           IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')]
@@ -456,7 +463,7 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
 
          >>> n1 = ip_network('192.0.2.0/28')
          >>> n2 = ip_network('192.0.2.1/32')
-         >>> list(n1.address_exclude(n2))
+         >>> list(n1.address_exclude(n2))  #doctest: +NORMALIZE_WHITESPACE
          [IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'),
           IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')]
 
@@ -471,10 +478,10 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
 
          >>> list(ip_network('192.0.2.0/24').subnets())
          [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]
-         >>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2))
+         >>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2))  #doctest: +NORMALIZE_WHITESPACE
          [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
           IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
-         >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26))
+         >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26))  #doctest: +NORMALIZE_WHITESPACE
          [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
           IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
          >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23))

Lib/ipaddress.py

@@ -206,10 +206,11 @@ def summarize_address_range(first, last):
     """Summarize a network range given the first and last IP addresses.
 
     Example:
-        >>> summarize_address_range(IPv4Address('192.0.2.0'),
+        >>> list(summarize_address_range(IPv4Address('192.0.2.0'),
-            IPv4Address('192.0.2.130'))
+        ...                              IPv4Address('192.0.2.130')))
+        ...                                #doctest: +NORMALIZE_WHITESPACE
         [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'),
-        IPv4Network('192.0.2.130/32')]
+         IPv4Network('192.0.2.130/32')]
 
     Args:
         first: the first IPv4Address or IPv6Address in the range.