Adding upstream version 0.10.1.upstream/0.10.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 2206 insertions, 0 deletions

diff --git a/netaddr/ip/__init__.py b/netaddr/ip/__init__.py
new file mode 100644
index 0000000..0669224
--- /dev/null
+++ b/netaddr/ip/__init__.py
@@ -0,0 +1,2206 @@
+#-----------------------------------------------------------------------------
+#   Copyright (c) 2008 by David P. D. Moss. All rights reserved.
+#
+#   Released under the BSD license. See the LICENSE file for details.
+#-----------------------------------------------------------------------------
+"""Routines for IPv4 and IPv6 addresses, subnets and ranges."""
+
+import sys as _sys
+
+from netaddr.core import AddrFormatError, AddrConversionError, num_bits, \
+    DictDotLookup, NOHOST, N, INET_ATON, INET_PTON, P, ZEROFILL, Z
+
+from netaddr.strategy import ipv4 as _ipv4, ipv6 as _ipv6
+
+from netaddr.compat import _sys_maxint, _iter_next, _iter_range, _is_str, _int_type, \
+    _str_type
+
+
+class BaseIP(object):
+    """
+    An abstract base class for common operations shared between various IP
+    related subclasses.
+
+    """
+    __slots__ = ('_value', '_module', '__weakref__')
+
+    def __init__(self):
+        """Constructor."""
+        self._value = None
+        self._module = None
+
+    def _set_value(self, value):
+        if not isinstance(value, _int_type):
+            raise TypeError('int argument expected, not %s' % type(value))
+        if not 0 <= value <= self._module.max_int:
+            raise AddrFormatError('value out of bounds for an %s address!' \
+                % self._module.family_name)
+        self._value = value
+
+    value = property(lambda self: self._value, _set_value,
+        doc='a positive integer representing the value of IP address/subnet.')
+
+    def key(self):
+        """
+        :return: a key tuple that uniquely identifies this IP address.
+        """
+        return NotImplemented
+
+    def sort_key(self):
+        """
+        :return: A key tuple used to compare and sort this `IPAddress`
+            correctly.
+        """
+        return NotImplemented
+
+    def __hash__(self):
+        """
+        :return: A hash value uniquely identifying this IP object.
+        """
+        return hash(self.key())
+
+    def __eq__(self, other):
+        """
+        :param other: an `IPAddress` or `IPNetwork` object.
+
+        :return: ``True`` if this `IPAddress` or `IPNetwork` object is
+            equivalent to ``other``, ``False`` otherwise.
+        """
+        try:
+            return self.key() == other.key()
+        except (AttributeError, TypeError):
+            return NotImplemented
+
+    def __ne__(self, other):
+        """
+        :param other: an `IPAddress` or `IPNetwork` object.
+
+        :return: ``True`` if this `IPAddress` or `IPNetwork` object is
+            not equivalent to ``other``, ``False`` otherwise.
+        """
+        try:
+            return self.key() != other.key()
+        except (AttributeError, TypeError):
+            return NotImplemented
+
+    def __lt__(self, other):
+        """
+        :param other: an `IPAddress` or `IPNetwork` object.
+
+        :return: ``True`` if this `IPAddress` or `IPNetwork` object is
+            less than ``other``, ``False`` otherwise.
+        """
+        try:
+            return self.sort_key() < other.sort_key()
+        except (AttributeError, TypeError):
+            return NotImplemented
+
+    def __le__(self, other):
+        """
+        :param other: an `IPAddress` or `IPNetwork` object.
+
+        :return: ``True`` if this `IPAddress` or `IPNetwork` object is
+            less than or equal to ``other``, ``False`` otherwise.
+        """
+        try:
+            return self.sort_key() <= other.sort_key()
+        except (AttributeError, TypeError):
+            return NotImplemented
+
+    def __gt__(self, other):
+        """
+        :param other: an `IPAddress` or `IPNetwork` object.
+
+        :return: ``True`` if this `IPAddress` or `IPNetwork` object is
+            greater than ``other``, ``False`` otherwise.
+        """
+        try:
+            return self.sort_key() > other.sort_key()
+        except (AttributeError, TypeError):
+            return NotImplemented
+
+    def __ge__(self, other):
+        """
+        :param other: an `IPAddress` or `IPNetwork` object.
+
+        :return: ``True`` if this `IPAddress` or `IPNetwork` object is
+            greater than or equal to ``other``, ``False`` otherwise.
+        """
+        try:
+            return self.sort_key() >= other.sort_key()
+        except (AttributeError, TypeError):
+            return NotImplemented
+
+    def is_unicast(self):
+        """:return: ``True`` if this IP is unicast, ``False`` otherwise"""
+        return not self.is_multicast()
+
+    def is_multicast(self):
+        """:return: ``True`` if this IP is multicast, ``False`` otherwise"""
+        if self._module == _ipv4:
+            return self in IPV4_MULTICAST
+        elif self._module == _ipv6:
+            return self in IPV6_MULTICAST
+
+    def is_loopback(self):
+        """
+        :return: ``True`` if this IP is loopback address (not for network
+            transmission), ``False`` otherwise.
+            References: RFC 3330 and 4291.
+
+        .. note:: |ipv4_in_ipv6_handling|
+        """
+        if self._module.version == 4:
+            return self in IPV4_LOOPBACK
+        elif self._module.version == 6:
+            return self in IPV6_LOOPBACK
+
+    def is_private(self):
+        """
+        :return: ``True`` if this IP is for internal/private use only
+            (i.e. non-public), ``False`` otherwise. Reference: RFCs 1918,
+            3330, 4193, 3879 and 2365.
+
+        .. note:: |ipv4_in_ipv6_handling|
+
+        .. deprecated:: 0.10.0
+            The ``is_private`` method has been mixing several different address types together
+            which could lead to unexpected results. There are more precise
+            replacements for subset of the addresses handled by ``is_private`` today:
+
+            * :meth:`is_link_local`
+            * :meth:`is_ipv4_private_use`
+            * :meth:`is_ipv6_unique_local`
+
+            There is also the :meth:`is_global` method that lets you handle all globally
+            reachable (or not) addresses.
+
+            The following address blocks currently handled by ``is_private`` have no
+            convenience methods and you'll have to handle them manually or request a method
+            addition:
+
+            * ``100.64.0.0/10`` – Shared Address Space
+            * ``192.0.0.0/24`` – IETF Protocol Assignments
+            * ``198.18.0.0/15`` – Benchmarking
+            * ``239.0.0.0``-``239.255.255.255``
+        """
+        if self._module.version == 4:
+            for cidr in IPV4_PRIVATEISH:
+                if self in cidr:
+                    return True
+        elif self._module.version == 6:
+            for cidr in IPV6_PRIVATEISH:
+                if self in cidr:
+                    return True
+
+        if self.is_link_local():
+            return True
+
+        return False
+
+    def is_link_local(self):
+        """
+        :return: ``True`` if this IP is link-local address ``False`` otherwise.
+            Reference: RFCs 3927 and 4291.
+
+        .. note:: |ipv4_in_ipv6_handling|
+        """
+        if self._module.version == 4:
+            return self in IPV4_LINK_LOCAL
+        elif self._module.version == 6:
+            return self in IPV6_LINK_LOCAL
+
+    def is_reserved(self):
+        """
+        :return: ``True`` if this IP is in IANA reserved range, ``False``
+            otherwise. Reference: RFCs 3330 and 3171.
+
+        .. note:: |ipv4_in_ipv6_handling|
+        """
+        if self._module.version == 4:
+            for cidr in IPV4_RESERVED:
+                if self in cidr:
+                    return True
+        elif self._module.version == 6:
+            for cidr in IPV6_RESERVED:
+                if self in cidr:
+                    return True
+        return False
+
+    def is_ipv4_mapped(self):
+        """
+        :return: ``True`` if this IP is IPv4-compatible IPv6 address, ``False``
+            otherwise.
+        """
+        return self._module.version == 6 and (self._value >> 32) == 0xffff
+
+    def is_ipv4_compat(self):
+        """
+        :return: ``True`` if this IP is IPv4-mapped IPv6 address, ``False``
+            otherwise.
+        """
+        return self._module.version == 6 and (self._value >> 32) == 0
+
+    @property
+    def info(self):
+        """
+        A record dict containing IANA registration details for this IP address
+        if available, None otherwise.
+        """
+        #   Lazy loading of IANA data structures.
+        from netaddr.ip.iana import query
+        return DictDotLookup(query(self))
+
+    @property
+    def version(self):
+        """the IP protocol version represented by this IP object."""
+        return self._module.version
+
+
+class IPAddress(BaseIP):
+    """
+    An individual IPv4 or IPv6 address without a net mask or subnet prefix.
+
+    To support these and other network based operations, see `IPNetwork`.
+
+    """
+    __slots__ = ()
+
+    def __init__(self, addr, version=None, flags=0):
+        """
+        Constructor.
+
+        :param addr: an IPv4 or IPv6 address which may be represented in an
+            accepted string format, as an unsigned integer or as another
+            IPAddress object (copy construction).
+
+        :param version: (optional) optimizes version detection if specified
+            and distinguishes between IPv4 and IPv6 for addresses with an
+            equivalent integer value.
+
+        :param flags: (optional) decides which rules are applied to the
+            interpretation of the addr value if passed as a string.
+
+            Matters only in IPv4 context.
+
+            Allowed flag values:
+
+            * The default (``0``) or :data:`INET_ATON`. Follows `inet_aton semantics
+              <https://www.netmeister.org/blog/inet_aton.html>`_ and allows all kinds of
+              weird-looking addresses to be parsed. For example:
+
+              >>> IPAddress('1')
+              IPAddress('0.0.0.1')
+              >>> IPAddress('1.0xf')
+              IPAddress('1.0.0.15')
+              >>> IPAddress('010.020.030.040')
+              IPAddress('8.16.24.32')
+
+            * ``INET_ATON | ZEROFILL`` or :data:`ZEROFILL` – like the default, except leading zeros are discarded:
+
+              >>> IPAddress('010', flags=INET_ATON | ZEROFILL)
+              IPAddress('0.0.0.10')
+
+            * :data:`INET_PTON` – requires four decimal octets:
+
+              >>> IPAddress('10.0.0.1', flags=INET_PTON)
+              IPAddress('10.0.0.1')
+
+              Leading zeros may be ignored or rejected, depending on the platform.
+
+            * ``INET_PTON | ZEROFILL`` – like :data:`INET_PTON`, except leading zeros are
+              discarded:
+
+              >>> IPAddress('010.020.030.040', flags=INET_PTON | ZEROFILL)
+              IPAddress('10.20.30.40')
+
+        .. versionchanged:: 0.10.0
+            The default IPv4 parsing mode is scheduled to become :data:`INET_PTON` in the next
+            major release.
+        """
+        super(IPAddress, self).__init__()
+
+        if flags & ~(INET_PTON | ZEROFILL | INET_ATON):
+            raise ValueError('Unrecognized IPAddress flags value: %s' % (flags,))
+
+        if flags & INET_ATON and flags & INET_PTON:
+            raise ValueError('INET_ATON and INET_PTON are mutually exclusive')
+
+        if isinstance(addr, BaseIP):
+            #   Copy constructor.
+            if version is not None and version != addr._module.version:
+                raise ValueError('cannot switch IP versions using '
+                    'copy constructor!')
+            self._value = addr._value
+            self._module = addr._module
+        else:
+            #   Explicit IP address version.
+            if version is not None:
+                if version == 4:
+                    self._module = _ipv4
+                elif version == 6:
+                    self._module = _ipv6
+                else:
+                    raise ValueError('%r is an invalid IP version!' % version)
+
+            if _is_str(addr) and '/' in addr:
+                raise ValueError('%s() does not support netmasks or subnet' \
+                    ' prefixes! See documentation for details.'
+                    % self.__class__.__name__)
+
+            if self._module is None:
+                #   IP version is implicit, detect it from addr.
+                if isinstance(addr, _int_type):
+                    try:
+                        if 0 <= int(addr) <= _ipv4.max_int:
+                            self._value = int(addr)
+                            self._module = _ipv4
+                        elif _ipv4.max_int < int(addr) <= _ipv6.max_int:
+                            self._value = int(addr)
+                            self._module = _ipv6
+                    except ValueError:
+                        pass
+                else:
+                    for module in _ipv4, _ipv6:
+                        try:
+                            self._value = module.str_to_int(addr, flags)
+                        except:
+                            continue
+                        else:
+                            self._module = module
+                            break
+
+                if self._module is None:
+                    raise AddrFormatError('failed to detect a valid IP ' \
+                        'address from %r' % addr)
+            else:
+                #   IP version is explicit.
+                if _is_str(addr):
+                    try:
+                        self._value = self._module.str_to_int(addr, flags)
+                    except AddrFormatError:
+                        raise AddrFormatError('base address %r is not IPv%d'
+                            % (addr, self._module.version))
+                else:
+                    if 0 <= int(addr) <= self._module.max_int:
+                        self._value = int(addr)
+                    else:
+                        raise AddrFormatError('bad address format: %r' % (addr,))
+
+    def __getstate__(self):
+        """:returns: Pickled state of an `IPAddress` object."""
+        return self._value, self._module.version
+
+    def __setstate__(self, state):
+        """
+        :param state: data used to unpickle a pickled `IPAddress` object.
+
+        """
+        value, version = state
+
+        self._value = value
+
+        if version == 4:
+            self._module = _ipv4
+        elif version == 6:
+            self._module = _ipv6
+        else:
+            raise ValueError('unpickling failed for object state: %s' \
+                % str(state))
+
+    def netmask_bits(self):
+        """
+        @return: If this IP is a valid netmask, the number of non-zero
+            bits are returned, otherwise it returns the width in bits for
+            the IP address version.
+        """
+        if not self.is_netmask():
+            return self._module.width
+
+        # the '0' address (e.g. 0.0.0.0 or 0000::) is a valid netmask with
+        # no bits set.
+        if self._value == 0:
+            return 0
+
+        i_val = self._value
+        numbits = 0
+
+        while i_val > 0:
+            if i_val & 1 == 1:
+                break
+            numbits += 1
+            i_val >>= 1
+
+        mask_length = self._module.width - numbits
+
+        if not 0 <= mask_length <= self._module.width:
+            raise ValueError('Unexpected mask length %d for address type!' \
+                % mask_length)
+
+        return mask_length
+
+    def is_hostmask(self):
+        """
+        :return: ``True`` if this IP address host mask, ``False`` otherwise.
+        """
+        int_val = self._value + 1
+        return (int_val & (int_val - 1) == 0)
+
+    def is_netmask(self):
+        """
+        :return: ``True`` if this IP address network mask, ``False`` otherwise.
+        """
+        int_val = (self._value ^ self._module.max_int) + 1
+        return (int_val & (int_val - 1) == 0)
+
+    def __iadd__(self, num):
+        """
+        Increases the numerical value of this IPAddress by num.
+
+        An IndexError is raised if result exceeds maximum IP address value or
+        is less than zero.
+
+        :param num: size of IP address increment.
+        """
+        new_value = int(self._value + num)
+        if 0 <= new_value <= self._module.max_int:
+            self._value = new_value
+            return self
+        raise IndexError('result outside valid IP address boundary!')
+
+    def __isub__(self, num):
+        """
+        Decreases the numerical value of this IPAddress by num.
+
+        An IndexError is raised if result is less than zero or exceeds maximum
+        IP address value.
+
+        :param num: size of IP address decrement.
+        """
+        new_value = int(self._value - num)
+        if 0 <= new_value <= self._module.max_int:
+            self._value = new_value
+            return self
+        raise IndexError('result outside valid IP address boundary!')
+
+    def __add__(self, num):
+        """
+        Add the numerical value of this IP address to num and provide the
+        result as a new IPAddress object.
+
+        :param num: size of IP address increase.
+
+        :return: a new IPAddress object with its numerical value increased by num.
+        """
+        new_value = int(self._value + num)
+        if 0 <= new_value <= self._module.max_int:
+            return self.__class__(new_value, self._module.version)
+        raise IndexError('result outside valid IP address boundary!')
+
+    __radd__ = __add__
+
+    def __sub__(self, num):
+        """
+        Subtract the numerical value of this IP address from num providing
+        the result as a new IPAddress object.
+
+        :param num: size of IP address decrease.
+
+        :return: a new IPAddress object with its numerical value decreased by num.
+        """
+        new_value = int(self._value - num)
+        if 0 <= new_value <= self._module.max_int:
+            return self.__class__(new_value, self._module.version)
+        raise IndexError('result outside valid IP address boundary!')
+
+    def __rsub__(self, num):
+        """
+        Subtract num (lvalue) from the numerical value of this IP address
+        (rvalue) providing the result as a new IPAddress object.
+
+        :param num: size of IP address decrease.
+
+        :return: a new IPAddress object with its numerical value decreased by num.
+        """
+        new_value = int(num - self._value)
+        if 0 <= new_value <= self._module.max_int:
+            return self.__class__(new_value, self._module.version)
+        raise IndexError('result outside valid IP address boundary!')
+
+    def key(self):
+        """
+        :return: a key tuple that uniquely identifies this IP address.
+        """
+        #   NB - we return the value here twice because this IP Address may
+        #   be sorted with a list of networks and it should still end up
+        #   in the expected order.
+        return self._module.version, self._value
+
+    def sort_key(self):
+        """:return: A key tuple used to compare and sort this `IPAddress` correctly."""
+        return self._module.version, self._value, self._module.width
+
+    def __int__(self):
+        """:return: the value of this IP address as an unsigned integer"""
+        return self._value
+
+    def __long__(self):
+        """:return: the value of this IP address as an unsigned integer"""
+        return self._value
+
+    def __oct__(self):
+        """:return: an octal string representation of this IP address."""
+        #   Python 2.x
+        if self._value == 0:
+            return '0'
+        return '0%o' % self._value
+
+    def __hex__(self):
+        """:return: a hexadecimal string representation of this IP address."""
+        #   Python 2.x
+        return '0x%x' % self._value
+
+    def __index__(self):
+        """
+        :return: return the integer value of this IP address when called by \
+            hex(), oct() or bin().
+        """
+        #   Python 3.x
+        return self._value
+
+    def __bytes__(self):
+        """ 
+        :return: a bytes object equivalent to this IP address. In network
+            byte order, big-endian.
+        """
+        #   Python 3.x
+        return self._value.to_bytes(self._module.width//8, 'big')
+
+    def bits(self, word_sep=None):
+        """
+        :param word_sep: (optional) the separator to insert between words.
+            Default: None - use default separator for address type.
+
+        :return: the value of this IP address as a binary digit string."""
+        return self._module.int_to_bits(self._value, word_sep)
+
+    @property
+    def packed(self):
+        """The value of this IP address as a packed binary string."""
+        return self._module.int_to_packed(self._value)
+
+    @property
+    def words(self):
+        """
+        A list of unsigned integer words (octets for IPv4, hextets for IPv6)
+        found in this IP address.
+        """
+        return self._module.int_to_words(self._value)
+
+    @property
+    def bin(self):
+        """
+        The value of this IP address in standard Python binary
+        representational form (0bxxx). A back port of the format provided by
+        the builtin bin() function found in Python 2.6.x and higher.
+        """
+        return self._module.int_to_bin(self._value)
+
+    @property
+    def reverse_dns(self):
+        """The reverse DNS lookup record for this IP address"""
+        return self._module.int_to_arpa(self._value)
+
+    def ipv4(self):
+        """
+        Raises an `AddrConversionError` if IPv6 address cannot be converted
+        to IPv4.
+
+        :return: A numerically equivalent version 4 `IPAddress` object.
+        """
+        ip = None
+        klass = self.__class__
+
+        if self._module.version == 4:
+            ip = klass(self._value, 4)
+        elif self._module.version == 6:
+            if 0 <= self._value <= _ipv4.max_int:
+                ip = klass(self._value, 4)
+            elif _ipv4.max_int <= self._value <= 0xffffffffffff:
+                ip = klass(self._value - 0xffff00000000, 4)
+            else:
+                raise AddrConversionError('IPv6 address %s unsuitable for ' \
+                    'conversion to IPv4!' % self)
+        return ip
+
+    def ipv6(self, ipv4_compatible=False):
+        """
+        .. note:: The IPv4-mapped IPv6 address format is now considered \
+            deprecated. See RFC 4291 or later for details.
+
+        :param ipv4_compatible: If ``True`` returns an IPv4-mapped address
+            (::ffff:x.x.x.x), an IPv4-compatible (::x.x.x.x) address
+            otherwise. Default: False (IPv4-mapped).
+
+        :return: A numerically equivalent version 6 `IPAddress` object.
+        """
+        ip = None
+        klass = self.__class__
+
+        if self._module.version == 6:
+            if ipv4_compatible and \
+                (0xffff00000000 <= self._value <= 0xffffffffffff):
+                ip = klass(self._value - 0xffff00000000, 6)
+            else:
+                ip = klass(self._value, 6)
+        elif self._module.version == 4:
+            #   IPv4-Compatible IPv6 address
+            ip = klass(self._value, 6)
+            if not ipv4_compatible:
+                #   IPv4-Mapped IPv6 address
+                ip = klass(0xffff00000000 + self._value, 6)
+
+        return ip
+
+    def format(self, dialect=None):
+        """
+        Only relevant for IPv6 addresses. Has no effect for IPv4.
+
+        :param dialect: One of the :ref:`ipv6_formatting_dialects`.
+
+        :return: an alternate string representation for this IP address.
+        """
+        if dialect is not None:
+            if not hasattr(dialect, 'word_fmt'):
+                raise TypeError(
+                    'custom dialects should subclass ipv6_verbose!')
+        return self._module.int_to_str(self._value, dialect=dialect)
+
+    def __or__(self, other):
+        """
+        :param other: An `IPAddress` object (or other int-like object).
+
+        :return: bitwise OR (x | y) between the integer value of this IP
+            address and ``other``.
+        """
+        return self.__class__(self._value | int(other), self._module.version)
+
+    def __and__(self, other):
+        """
+        :param other: An `IPAddress` object (or other int-like object).
+
+        :return: bitwise AND (x & y) between the integer value of this IP
+            address and ``other``.
+        """
+        return self.__class__(self._value & int(other), self._module.version)
+
+    def __xor__(self, other):
+        """
+        :param other: An `IPAddress` object (or other int-like object).
+
+        :return: bitwise exclusive OR (x ^ y) between the integer value of
+            this IP address and ``other``.
+        """
+        return self.__class__(self._value ^ int(other), self._module.version)
+
+    def __lshift__(self, numbits):
+        """
+        :param numbits: size of bitwise shift.
+
+        :return: an `IPAddress` object based on this one with its integer
+            value left shifted by ``numbits``.
+        """
+        return self.__class__(self._value << numbits, self._module.version)
+
+    def __rshift__(self, numbits):
+        """
+        :param numbits: size of bitwise shift.
+
+        :return: an `IPAddress` object based on this one with its integer
+            value right shifted by ``numbits``.
+        """
+        return self.__class__(self._value >> numbits, self._module.version)
+
+    def __nonzero__(self):
+        """:return: ``True`` if the numerical value of this IP address is not \
+            zero, ``False`` otherwise."""
+        #   Python 2.x.
+        return bool(self._value)
+
+    __bool__ = __nonzero__  #   Python 3.x.
+
+    def __str__(self):
+        """:return: IP address in presentational format"""
+        return self._module.int_to_str(self._value)
+
+    def __repr__(self):
+        """:return: Python statement to create an equivalent object"""
+        return "%s('%s')" % (self.__class__.__name__, self)
+
+    def to_canonical(self):
+        """
+        Converts the address to IPv4 if it is an IPv4-mapped IPv6 address (`RFC 4291
+        Section 2.5.5.2 <https://datatracker.ietf.org/doc/html/rfc4291.html#section-2.5.5.2>`_),
+        otherwise returns the address as-is.
+
+        >>> # IPv4-mapped IPv6
+        >>> IPAddress('::ffff:10.0.0.1').to_canonical()
+        IPAddress('10.0.0.1')
+        >>>
+        >>> # Everything else
+        >>> IPAddress('::1').to_canonical()
+        IPAddress('::1')
+        >>> IPAddress('10.0.0.1').to_canonical()
+        IPAddress('10.0.0.1')
+
+        .. versionadded:: 0.10.0
+        """
+        if not self.is_ipv4_mapped():
+            return self
+        return self.ipv4()
+
+    def is_global(self):
+        """
+        Returns ``True`` if this address is considered globally reachable, ``False`` otherwise.
+
+        An address is considered globally reachable if it's not a special-purpose address
+        or it's a special-purpose address listed as globally reachable in the relevant
+        registries:
+
+        * |iana_special_ipv4|
+        * |iana_special_ipv6|
+
+        Addresses for which the ``Globally Reachable`` value is ``N/A`` are not considered
+        globally reachable.
+
+        Address blocks with set termination date are not taken into consideration.
+
+        Whether or not an address can actually be reached in any local or global context will
+        depend on the network configuration and may differ from what this method returns.
+
+        Currently there can be addresses that are neither ``is_global()`` nor :meth:`is_private`.
+        There are also addresses that are both. All things being equal ``is_global()`` should
+        be considered more trustworthy.
+
+        Examples:
+
+        >>> IPAddress('1.1.1.1').is_global()
+        True
+        >>> IPAddress('::1').is_global()
+        False
+
+        .. note:: |ipv4_in_ipv6_handling|
+        """
+        if self._module.version == 4:
+            not_reachable = IPV4_NOT_GLOBALLY_REACHABLE
+            exceptions = IPV4_NOT_GLOBALLY_REACHABLE_EXCEPTIONS
+        else:
+            not_reachable = IPV6_NOT_GLOBALLY_REACHABLE
+            exceptions = IPV6_NOT_GLOBALLY_REACHABLE_EXCEPTIONS
+
+        return (
+            not any(self in net for net in not_reachable)
+            or any(self in net for net in exceptions)
+        )
+
+    def is_ipv4_private_use(self):
+        """
+        Returns ``True`` if this address is an IPv4 private-use address as defined in
+        :rfc:`1918`.
+
+        The private-use address blocks:
+
+        * ``10.0.0.0/8``
+        * ``172.16.0.0/12``
+        * ``192.168.0.0/16``
+
+        .. note:: |ipv4_in_ipv6_handling|
+
+        .. versionadded:: 0.10.0
+        """
+        return self._module.version == 4 and any(self in cidr for cidr in IPV4_PRIVATE_USE)
+
+    def is_ipv6_unique_local(self):
+        """
+        Returns ``True`` if this address is an IPv6 unique local address as defined in
+        :rfc:`4193` and listed in |iana_special_ipv6|.
+
+        The IPv6 unique local address block: ``fc00::/7``.
+
+        .. versionadded:: 0.10.0
+        """
+        return self._module.version == 6 and self in IPV6_UNIQUE_LOCAL
+
+
+class IPListMixin(object):
+    """
+    A mixin class providing shared list-like functionality to classes
+    representing groups of IP addresses.
+
+    """
+    __slots__ = ()
+    def __iter__(self):
+        """
+        :return: An iterator providing access to all `IPAddress` objects
+            within range represented by this ranged IP object.
+        """
+        start_ip = IPAddress(self.first, self._module.version)
+        end_ip = IPAddress(self.last, self._module.version)
+        return iter_iprange(start_ip, end_ip)
+
+    @property
+    def size(self):
+        """
+        The total number of IP addresses within this ranged IP object.
+        """
+        return int(self.last - self.first + 1)
+
+    def __len__(self):
+        """
+        :return: the number of IP addresses in this ranged IP object. Raises
+            an `IndexError` if size > system max int (a Python 2.x
+            limitation). Use the .size property for subnets of any size.
+        """
+        size = self.size
+        if size > _sys_maxint:
+            raise IndexError(("range contains more than %d (sys.maxint) "
+               "IP addresses! Use the .size property instead." % _sys_maxint))
+        return size
+
+    def __getitem__(self, index):
+        """
+        :return: The IP address(es) in this `IPNetwork` object referenced by
+            index or slice. As slicing can produce large sequences of objects
+            an iterator is returned instead of the more usual `list`.
+        """
+        item = None
+
+        if hasattr(index, 'indices'):
+            if self._module.version == 6:
+                raise TypeError('IPv6 slices are not supported!')
+
+            (start, stop, step) = index.indices(self.size)
+
+            if (start + step < 0) or (step > stop):
+                #   step value exceeds start and stop boundaries.
+                item = iter([IPAddress(self.first, self._module.version)])
+            else:
+                start_ip = IPAddress(self.first + start, self._module.version)
+                end_ip = IPAddress(self.first + stop - step, self._module.version)
+                item = iter_iprange(start_ip, end_ip, step)
+        else:
+            try:
+                index = int(index)
+                if (- self.size) <= index < 0:
+                    #   negative index.
+                    item = IPAddress(self.last + index + 1, self._module.version)
+                elif 0 <= index <= (self.size - 1):
+                    #   Positive index or zero index.
+                    item = IPAddress(self.first + index, self._module.version)
+                else:
+                    raise IndexError('index out range for address range size!')
+            except ValueError:
+                raise TypeError('unsupported index type %r!' % index)
+
+        return item
+
+    def __contains__(self, other):
+        """
+        :param other: an `IPAddress` or ranged IP object.
+
+        :return: ``True`` if other falls within the boundary of this one,
+            ``False`` otherwise.
+        """
+        if isinstance(other, BaseIP):
+            if self._module.version != other._module.version:
+                return False
+            if isinstance(other, IPAddress):
+                return other._value >= self.first and other._value <= self.last
+            # Assume that we (and the other) provide .first and .last.
+            return other.first >= self.first and other.last <= self.last
+
+        # Whatever it is, try to interpret it as IPAddress.
+        return IPAddress(other) in self
+
+    def __nonzero__(self):
+        """
+        Ranged IP objects always represent a sequence of at least one IP
+        address and are therefore always True in the boolean context.
+        """
+        #   Python 2.x.
+        return True
+
+    __bool__ = __nonzero__  #   Python 3.x.
+
+
+def parse_ip_network(module, addr, implicit_prefix=False, flags=0):
+    if isinstance(addr, tuple):
+        #   CIDR integer tuple
+        if len(addr) != 2:
+            raise AddrFormatError('invalid %s tuple!' % module.family_name)
+        value, prefixlen = addr
+
+        if not(0 <= value <= module.max_int):
+            raise AddrFormatError('invalid address value for %s tuple!'
+                % module.family_name)
+        if not(0 <= prefixlen <= module.width):
+            raise AddrFormatError('invalid prefix for %s tuple!' \
+                % module.family_name)
+    elif isinstance(addr, _str_type):
+        #   CIDR-like string subnet
+        if implicit_prefix:
+            #TODO: deprecate this option in netaddr 0.8.x
+            addr = cidr_abbrev_to_verbose(addr)
+
+        if '/' in addr:
+            val1, val2 = addr.split('/', 1)
+        else:
+            val1 = addr
+            val2 = None
+
+        try:
+            ip = IPAddress(val1, module.version, flags=INET_PTON)
+        except AddrFormatError:
+            if module.version == 4:
+                #   Try a partial IPv4 network address...
+                expanded_addr = _ipv4.expand_partial_address(val1)
+                ip = IPAddress(expanded_addr, module.version, flags=INET_PTON)
+            else:
+                raise AddrFormatError('invalid IPNetwork address %s!' % addr)
+        value = ip._value
+
+        try:
+            #   Integer CIDR prefix.
+            prefixlen = int(val2)
+        except TypeError:
+            if val2 is None:
+                #   No prefix was specified.
+                prefixlen = module.width
+        except ValueError:
+            #   Not an integer prefix, try a netmask/hostmask prefix.
+            mask = IPAddress(val2, module.version, flags=INET_PTON)
+            if mask.is_netmask():
+                prefixlen = module.netmask_to_prefix[mask._value]
+            elif mask.is_hostmask():
+                prefixlen = module.hostmask_to_prefix[mask._value]
+            else:
+                raise AddrFormatError('addr %r is not a valid IPNetwork!' \
+                    % addr)
+
+        if not 0 <= prefixlen <= module.width:
+            raise AddrFormatError('invalid prefix for %s address!' \
+                % module.family_name)
+    else:
+        raise TypeError('unexpected type %s for addr arg' % type(addr))
+
+    if flags & NOHOST:
+        #   Remove host bits.
+        netmask = module.prefix_to_netmask[prefixlen]
+        value = value & netmask
+
+    return value, prefixlen
+
+
+class IPNetwork(BaseIP, IPListMixin):
+    """
+    An IPv4 or IPv6 network or subnet.
+
+    A combination of an IP address and a network mask.
+
+    Accepts CIDR and several related variants :
+
+    a) Standard CIDR::
+
+        x.x.x.x/y -> 192.0.2.0/24
+        x::/y -> fe80::/10
+
+    b) Hybrid CIDR format (netmask address instead of prefix), where 'y' \
+       address represent a valid netmask::
+
+        x.x.x.x/y.y.y.y -> 192.0.2.0/255.255.255.0
+        x::/y:: -> fe80::/ffc0::
+
+    c) ACL hybrid CIDR format (hostmask address instead of prefix like \
+       Cisco's ACL bitmasks), where 'y' address represent a valid netmask::
+
+        x.x.x.x/y.y.y.y -> 192.0.2.0/0.0.0.255
+        x::/y:: -> fe80::/3f:ffff:ffff:ffff:ffff:ffff:ffff:ffff
+
+    d) Abbreviated CIDR format (as of netaddr 0.7.x this requires the \
+       optional constructor argument ``implicit_prefix=True``)::
+
+        x       -> 192
+        x/y     -> 10/8
+        x.x/y   -> 192.168/16
+        x.x.x/y -> 192.168.0/24
+
+        which are equivalent to::
+
+        x.0.0.0/y   -> 192.0.0.0/24
+        x.0.0.0/y   -> 10.0.0.0/8
+        x.x.0.0/y   -> 192.168.0.0/16
+        x.x.x.0/y   -> 192.168.0.0/24
+
+       .. deprecated:: 0.10.0
+
+    .. warning::
+
+        The next release (0.9.0) will contain a backwards incompatible change
+        connected to handling of RFC 6164 IPv6 addresses (/127 and /128 subnets).
+        When iterating ``IPNetwork`` and ``IPNetwork.iter_hosts()`` the first
+        addresses in the networks will no longer be excluded and ``broadcast``
+        will be ``None``.
+    """
+    __slots__ = ('_prefixlen',)
+
+    def __init__(self, addr, implicit_prefix=False, version=None, flags=0):
+        """
+        Constructor.
+
+        :param addr: an IPv4 or IPv6 address with optional CIDR prefix,
+            netmask or hostmask. May be an IP address in presentation
+            (string) format, an tuple containing and integer address and a
+            network prefix, or another IPAddress/IPNetwork object (copy
+            construction).
+
+        :param implicit_prefix: (optional) if True, the constructor uses
+            classful IPv4 rules to select a default prefix when one is not
+            provided. If False it uses the length of the IP address version.
+            (default: False)
+
+            .. deprecated:: 0.10.0
+
+        :param version: (optional) optimizes version detection if specified
+            and distinguishes between IPv4 and IPv6 for addresses with an
+            equivalent integer value.
+
+        :param flags: (optional) decides which rules are applied to the
+            interpretation of the addr value. Currently only supports the
+            :data:`NOHOST` option.
+
+            >>> IPNetwork('1.2.3.4/24')
+            IPNetwork('1.2.3.4/24')
+            >>> IPNetwork('1.2.3.4/24', flags=NOHOST)
+            IPNetwork('1.2.3.0/24')
+        """
+        super(IPNetwork, self).__init__()
+
+        if flags & ~NOHOST:
+            raise ValueError('Unrecognized IPAddress flags value: %s' % (flags,))
+
+        value, prefixlen, module = None, None, None
+
+        if hasattr(addr, '_prefixlen'):
+            #   IPNetwork object copy constructor
+            value = addr._value
+            module = addr._module
+            prefixlen = addr._prefixlen
+        elif hasattr(addr, '_value'):
+            #   IPAddress object copy constructor
+            value = addr._value
+            module = addr._module
+            prefixlen = module.width
+        elif version == 4:
+            value, prefixlen = parse_ip_network(_ipv4, addr,
+                implicit_prefix=implicit_prefix, flags=flags)
+            module = _ipv4
+        elif version == 6:
+            value, prefixlen = parse_ip_network(_ipv6, addr,
+                implicit_prefix=implicit_prefix, flags=flags)
+            module = _ipv6
+        else:
+            if version is not None:
+                raise ValueError('%r is an invalid IP version!' % version)
+            try:
+                module = _ipv4
+                value, prefixlen = parse_ip_network(module, addr,
+                    implicit_prefix, flags)
+            except AddrFormatError:
+                try:
+                    module = _ipv6
+                    value, prefixlen = parse_ip_network(module, addr,
+                        implicit_prefix, flags)
+                except AddrFormatError:
+                    pass
+
+                if value is None:
+                    raise AddrFormatError('invalid IPNetwork %s' % (addr,))
+
+        self._value = value
+        self._prefixlen = prefixlen
+        self._module = module
+
+    def __getstate__(self):
+        """:return: Pickled state of an `IPNetwork` object."""
+        return self._value, self._prefixlen, self._module.version
+
+    def __setstate__(self, state):
+        """
+        :param state: data used to unpickle a pickled `IPNetwork` object.
+
+        """
+        value, prefixlen, version = state
+
+        self._value = value
+
+        if version == 4:
+            self._module = _ipv4
+        elif version == 6:
+            self._module = _ipv6
+        else:
+            raise ValueError('unpickling failed for object state %s' \
+                % (state,))
+
+        if 0 <= prefixlen <= self._module.width:
+            self._prefixlen = prefixlen
+        else:
+            raise ValueError('unpickling failed for object state %s' \
+                % (state,))
+
+    def _set_prefixlen(self, value):
+        if not isinstance(value, _int_type):
+            raise TypeError('int argument expected, not %s' % type(value))
+        if not 0 <= value <= self._module.width:
+            raise AddrFormatError('invalid prefix for an %s address!' \
+                % self._module.family_name)
+        self._prefixlen = value
+
+    prefixlen = property(lambda self: self._prefixlen, _set_prefixlen,
+        doc='size of the bitmask used to separate the network from the host bits')
+
+    @property
+    def ip(self):
+        """
+        The IP address of this `IPNetwork` object. This is may or may not be
+        the same as the network IP address which varies according to the value
+        of the CIDR subnet prefix.
+        """
+        return IPAddress(self._value, self._module.version)
+
+    @property
+    def network(self):
+        """The network address of this `IPNetwork` object."""
+        return IPAddress(self._value & self._netmask_int, self._module.version)
+
+    @property
+    def broadcast(self):
+        """The broadcast address of this `IPNetwork` object.
+
+        .. warning::
+
+            The next release (0.9.0) will contain a backwards incompatible change
+            connected to handling of RFC 6164 IPv6 addresses (/127 and /128 subnets).
+            ``broadcast`` will be ``None`` when dealing with those networks.
+        """
+        if (self._module.width - self._prefixlen) <= 1:
+            return None
+        else:
+            return IPAddress(self._value | self._hostmask_int, self._module.version)
+
+    @property
+    def first(self):
+        """
+        The integer value of first IP address found within this `IPNetwork`
+        object.
+        """
+        return self._value & (self._module.max_int ^ self._hostmask_int)
+
+    @property
+    def last(self):
+        """
+        The integer value of last IP address found within this `IPNetwork`
+        object.
+        """
+        hostmask = (1 << (self._module.width - self._prefixlen)) - 1
+        return self._value | hostmask
+
+    @property
+    def netmask(self):
+        """The subnet mask of this `IPNetwork` object."""
+        netmask = self._module.max_int ^ self._hostmask_int
+        return IPAddress(netmask, self._module.version)
+
+    @netmask.setter
+    def netmask(self, value):
+        """Set the prefixlen using a subnet mask"""
+        ip = IPAddress(value)
+
+        if ip.version != self.version:
+            raise ValueError("IP version mismatch: %s and %s" % (ip, self))
+
+        if not ip.is_netmask():
+            raise ValueError("Invalid subnet mask specified: %s" % str(value))
+
+        self.prefixlen = ip.netmask_bits()
+
+    @property
+    def _netmask_int(self):
+        """Same as self.netmask, but in integer format"""
+        return self._module.max_int ^ self._hostmask_int
+
+    @property
+    def hostmask(self):
+        """The host mask of this `IPNetwork` object."""
+        hostmask = (1 << (self._module.width - self._prefixlen)) - 1
+        return IPAddress(hostmask, self._module.version)
+
+    @property
+    def _hostmask_int(self):
+        """Same as self.hostmask, but in integer format"""
+        return (1 << (self._module.width - self._prefixlen)) - 1
+
+    @property
+    def cidr(self):
+        """
+        The true CIDR address for this `IPNetwork` object which omits any
+        host bits to the right of the CIDR subnet prefix.
+        """
+        return IPNetwork(
+                (self._value & self._netmask_int, self._prefixlen),
+                version=self._module.version)
+
+    def __iadd__(self, num):
+        """
+        Increases the value of this `IPNetwork` object by the current size
+        multiplied by ``num``.
+
+        An `IndexError` is raised if result exceeds maximum IP address value
+        or is less than zero.
+
+        :param num: (optional) number of `IPNetwork` blocks to increment \
+            this IPNetwork's value by.
+        """
+        new_value = int(self.network) + (self.size * num)
+
+        if (new_value + (self.size - 1)) > self._module.max_int:
+            raise IndexError('increment exceeds address boundary!')
+        if new_value < 0:
+            raise IndexError('increment is less than zero!')
+
+        self._value = new_value
+        return self
+
+    def __isub__(self, num):
+        """
+        Decreases the value of this `IPNetwork` object by the current size
+        multiplied by ``num``.
+
+        An `IndexError` is raised if result is less than zero or exceeds
+        maximum IP address value.
+
+        :param num: (optional) number of `IPNetwork` blocks to decrement \
+            this IPNetwork's value by.
+        """
+        new_value = int(self.network) - (self.size * num)
+
+        if new_value < 0:
+            raise IndexError('decrement is less than zero!')
+        if (new_value + (self.size - 1)) > self._module.max_int:
+            raise IndexError('decrement exceeds address boundary!')
+
+        self._value = new_value
+        return self
+
+    def __contains__(self, other):
+        """
+        :param other: an `IPAddress` or ranged IP object.
+
+        :return: ``True`` if other falls within the boundary of this one,
+            ``False`` otherwise.
+        """
+        if isinstance(other, BaseIP):
+            if self._module.version != other._module.version:
+                return False
+
+            # self_net will contain only the network bits.
+            shiftwidth = self._module.width - self._prefixlen
+            self_net = self._value >> shiftwidth
+            if isinstance(other, IPRange):
+                # IPRange has no _value.
+                # (self_net+1)<<shiftwidth is not our last address, but the one
+                # after the last one.
+                return ((self_net << shiftwidth) <= other._start._value and
+                        (((self_net + 1) << shiftwidth) > other._end._value))
+
+            other_net = other._value >> shiftwidth
+            if isinstance(other, IPAddress):
+                return other_net == self_net
+            if isinstance(other, IPNetwork):
+                return self_net == other_net and self._prefixlen <= other._prefixlen
+
+        # Whatever it is, try to interpret it as IPNetwork
+        return IPNetwork(other) in self
+
+    def key(self):
+        """
+        :return: A key tuple used to uniquely identify this `IPNetwork`.
+        """
+        return self._module.version, self.first, self.last
+
+    def sort_key(self):
+        """
+        :return: A key tuple used to compare and sort this `IPNetwork` correctly.
+        """
+        net_size_bits = self._prefixlen - 1
+        first = self._value & (self._module.max_int ^ self._hostmask_int)
+        host_bits = self._value - first
+        return self._module.version, first, net_size_bits, host_bits
+
+    def ipv4(self):
+        """
+        :return: A numerically equivalent version 4 `IPNetwork` object. \
+            Raises an `AddrConversionError` if IPv6 address cannot be \
+            converted to IPv4.
+        """
+        ip = None
+        klass = self.__class__
+
+        if self._module.version == 4:
+            ip = klass('%s/%d' % (self.ip, self.prefixlen))
+        elif self._module.version == 6:
+            if 0 <= self._value <= _ipv4.max_int:
+                addr = _ipv4.int_to_str(self._value)
+                ip = klass('%s/%d' % (addr, self.prefixlen - 96))
+            elif _ipv4.max_int <= self._value <= 0xffffffffffff:
+                addr = _ipv4.int_to_str(self._value - 0xffff00000000)
+                ip = klass('%s/%d' % (addr, self.prefixlen - 96))
+            else:
+                raise AddrConversionError('IPv6 address %s unsuitable for ' \
+                    'conversion to IPv4!' % self)
+        return ip
+
+    def ipv6(self, ipv4_compatible=False):
+        """
+        .. note:: the IPv4-mapped IPv6 address format is now considered \
+        deprecated. See RFC 4291 or later for details.
+
+        :param ipv4_compatible: If ``True`` returns an IPv4-mapped address
+            (::ffff:x.x.x.x), an IPv4-compatible (::x.x.x.x) address
+            otherwise. Default: False (IPv4-mapped).
+
+        :return: A numerically equivalent version 6 `IPNetwork` object.
+        """
+        ip = None
+        klass = self.__class__
+
+        if self._module.version == 6:
+            if ipv4_compatible and \
+                (0xffff00000000 <= self._value <= 0xffffffffffff):
+                ip = klass((self._value - 0xffff00000000, self._prefixlen),
+                    version=6)
+            else:
+                ip = klass((self._value, self._prefixlen), version=6)
+        elif self._module.version == 4:
+            if ipv4_compatible:
+                #   IPv4-Compatible IPv6 address
+                ip = klass((self._value, self._prefixlen + 96), version=6)
+            else:
+                #   IPv4-Mapped IPv6 address
+                ip = klass((0xffff00000000 + self._value,
+                            self._prefixlen + 96), version=6)
+
+        return ip
+
+    def previous(self, step=1):
+        """
+        :param step: the number of IP subnets between this `IPNetwork` object
+            and the expected subnet. Default: 1 (the previous IP subnet).
+
+        :return: The adjacent subnet preceding this `IPNetwork` object.
+        """
+        ip_copy = self.__class__('%s/%d' % (self.network, self.prefixlen),
+            self._module.version)
+        ip_copy -= step
+        return ip_copy
+
+    def next(self, step=1):
+        """
+        :param step: the number of IP subnets between this `IPNetwork` object
+            and the expected subnet. Default: 1 (the next IP subnet).
+
+        :return: The adjacent subnet succeeding this `IPNetwork` object.
+        """
+        ip_copy = self.__class__('%s/%d' % (self.network, self.prefixlen),
+            self._module.version)
+        ip_copy += step
+        return ip_copy
+
+    def supernet(self, prefixlen=0):
+        """
+        Provides a list of supernets for this `IPNetwork` object between the
+        size of the current prefix and (if specified) an endpoint prefix.
+
+        :param prefixlen: (optional) a CIDR prefix for the maximum supernet.
+            Default: 0 - returns all possible supernets.
+
+        :return: a tuple of supernet `IPNetwork` objects.
+        """
+        if not 0 <= prefixlen <= self._module.width:
+            raise ValueError('CIDR prefix /%d invalid for IPv%d!' \
+                % (prefixlen, self._module.version))
+
+        supernets = []
+        # Use a copy of self as we'll be editing it.
+        supernet = self.cidr
+        supernet._prefixlen = prefixlen
+        while supernet._prefixlen != self._prefixlen:
+            supernets.append(supernet.cidr)
+            supernet._prefixlen += 1
+        return supernets
+
+    def subnet(self, prefixlen, count=None, fmt=None):
+        """
+        A generator that divides up this IPNetwork's subnet into smaller
+        subnets based on a specified CIDR prefix.
+
+        :param prefixlen: a CIDR prefix indicating size of subnets to be
+            returned.
+
+        :param count: (optional) number of consecutive IP subnets to be
+            returned.
+
+        :return: an iterator containing IPNetwork subnet objects.
+        """
+        if not 0 <= self.prefixlen <= self._module.width:
+            raise ValueError('CIDR prefix /%d invalid for IPv%d!' \
+                % (prefixlen, self._module.version))
+
+        if not self.prefixlen <= prefixlen:
+            #   Don't return anything.
+            return
+
+        #   Calculate number of subnets to be returned.
+        width = self._module.width
+        max_subnets = 2 ** (width - self.prefixlen) // 2 ** (width - prefixlen)
+
+        if count is None:
+            count = max_subnets
+
+        if not 1 <= count <= max_subnets:
+            raise ValueError('count outside of current IP subnet boundary!')
+
+        base_subnet = self._module.int_to_str(self.first)
+        i = 0
+        while(i < count):
+            subnet = self.__class__('%s/%d' % (base_subnet, prefixlen),
+                self._module.version)
+            subnet.value += (subnet.size * i)
+            subnet.prefixlen = prefixlen
+            i += 1
+            yield subnet
+
+    def iter_hosts(self):
+        """
+        A generator that provides all the IP addresses that can be assigned
+        to hosts within the range of this IP object's subnet.
+
+        - for IPv4, the network and broadcast addresses are excluded, excepted \
+          when using /31 or /32 subnets as per RFC 3021.
+
+        - for IPv6, only Subnet-Router anycast address (first address in the \
+          network) is excluded as per RFC 4291 section 2.6.1, excepted when using \
+          /127 or /128 subnets as per RFC 6164.
+
+        .. warning::
+
+            The next release (0.9.0) will contain a backwards incompatible change
+            connected to handling of RFC 6164 IPv6 addresses (/127 and /128 subnets).
+            When iterating ``IPNetwork`` and ``IPNetwork.iter_hosts()`` the first
+            addresses in the networks will no longer be excluded.
+
+        :return: an IPAddress iterator
+        """
+        it_hosts = iter([])
+
+        # Common logic, first IP is always reserved.
+        first_usable_address = self.first + 1
+        if self._module.version == 4:
+            # IPv4 logic, last address is reserved for broadcast.
+            last_usable_address = self.last - 1
+        else:
+            # IPv6 logic, no broadcast address reserved.
+            last_usable_address = self.last
+
+        # If subnet has a size of less than 4, then it is a /31, /32, /127 or /128.
+        # Handle them as per RFC 3021 (IPv4) or RFC 6164 (IPv6), and don't reserve
+        # first or last IP address.
+        if self.size >= 4:
+            it_hosts = iter_iprange(
+                    IPAddress(first_usable_address, self._module.version),
+                    IPAddress(last_usable_address, self._module.version))
+        else:
+            it_hosts = iter_iprange(
+                    IPAddress(self.first, self._module.version),
+                    IPAddress(self.last, self._module.version))
+
+        return it_hosts
+
+    def __str__(self):
+        """:return: this IPNetwork in CIDR format"""
+        addr = self._module.int_to_str(self._value)
+        return "%s/%s" % (addr, self.prefixlen)
+
+    def __repr__(self):
+        """:return: Python statement to create an equivalent object"""
+        return "%s('%s')" % (self.__class__.__name__, self)
+
+
+class IPRange(BaseIP, IPListMixin):
+    """
+    An arbitrary IPv4 or IPv6 address range.
+
+    Formed from a lower and upper bound IP address. The upper bound IP cannot
+    be numerically smaller than the lower bound and the IP version of both
+    must match.
+
+    """
+    __slots__ = ('_start', '_end')
+
+    def __init__(self, start, end, flags=0):
+        """
+        Constructor.
+
+        :param start: an IPv4 or IPv6 address that forms the lower
+            boundary of this IP range.
+
+        :param end: an IPv4 or IPv6 address that forms the upper
+            boundary of this IP range.
+
+        :param flags: (optional) decides which rules are applied to the
+            interpretation of the start and end values. Refer to the :meth:`IPAddress.__init__`
+            documentation for details.
+
+        """
+        self._start = IPAddress(start, flags=flags)
+        self._module = self._start._module
+        self._end = IPAddress(end, self._module.version, flags=flags)
+        if int(self._start) > int(self._end):
+            raise AddrFormatError('lower bound IP greater than upper bound!')
+
+    def __getstate__(self):
+        """:return: Pickled state of an `IPRange` object."""
+        return self._start.value, self._end.value, self._module.version
+
+    def __setstate__(self, state):
+        """
+        :param state: data used to unpickle a pickled `IPRange` object.
+        """
+        start, end, version = state
+
+        self._start = IPAddress(start, version)
+        self._module = self._start._module
+        self._end = IPAddress(end, version)
+
+    def __contains__(self, other):
+        if isinstance(other, BaseIP):
+            if self._module.version != other._module.version:
+                return False
+            if isinstance(other, IPAddress):
+                return (self._start._value <= other._value and
+                        self._end._value >= other._value)
+            if isinstance(other, IPRange):
+                return (self._start._value <= other._start._value and
+                        self._end._value >= other._end._value)
+            if isinstance(other, IPNetwork):
+                shiftwidth = other._module.width - other._prefixlen
+                other_start = (other._value >> shiftwidth) << shiftwidth
+                # Start of the next network after other
+                other_next_start = other_start + (1 << shiftwidth)
+
+                return (self._start._value <= other_start and
+                        self._end._value > other_next_start)
+
+        # Whatever it is, try to interpret it as IPAddress.
+        return IPAddress(other) in self
+
+    @property
+    def first(self):
+        """The integer value of first IP address in this `IPRange` object."""
+        return int(self._start)
+
+    @property
+    def last(self):
+        """The integer value of last IP address in this `IPRange` object."""
+        return int(self._end)
+
+    def key(self):
+        """
+        :return: A key tuple used to uniquely identify this `IPRange`.
+        """
+        return self._module.version, self.first, self.last
+
+    def sort_key(self):
+        """
+        :return: A key tuple used to compare and sort this `IPRange` correctly.
+        """
+        skey = self._module.width - num_bits(self.size)
+        return self._module.version, self._start._value, skey
+
+    def cidrs(self):
+        """
+        The list of CIDR addresses found within the lower and upper bound
+        addresses of this `IPRange`.
+        """
+        return iprange_to_cidrs(self._start, self._end)
+
+    def __str__(self):
+        """:return: this `IPRange` in a common representational format."""
+        return "%s-%s" % (self._start, self._end)
+
+    def __repr__(self):
+        """:return: Python statement to create an equivalent object"""
+        return "%s('%s', '%s')" % (self.__class__.__name__,
+            self._start, self._end)
+
+
+def iter_unique_ips(*args):
+    """
+    :param args: A list of IP addresses and subnets passed in as arguments.
+
+    :return: A generator that flattens out IP subnets, yielding unique
+        individual IP addresses (no duplicates).
+    """
+    for cidr in cidr_merge(args):
+        for ip in cidr:
+            yield ip
+
+
+def cidr_abbrev_to_verbose(abbrev_cidr):
+    """
+    A function that converts abbreviated IPv4 CIDRs to their more verbose
+    equivalent.
+
+    :param abbrev_cidr: an abbreviated CIDR.
+
+    Uses the old-style classful IP address rules to decide on a default
+    subnet prefix if one is not explicitly provided.
+
+    Only supports IPv4 addresses.
+
+    Examples ::
+
+        10                  - 10.0.0.0/8
+        10/16               - 10.0.0.0/16
+        128                 - 128.0.0.0/16
+        128/8               - 128.0.0.0/8
+        192.168             - 192.168.0.0/16
+
+    :return: A verbose CIDR from an abbreviated CIDR or old-style classful \
+        network address. The original value if it was not recognised as a \
+        supported abbreviation.
+    """
+    #   Internal function that returns a prefix value based on the old IPv4
+    #   classful network scheme that has been superseded (almost) by CIDR.
+    def classful_prefix(octet):
+        octet = int(octet)
+        if not 0 <= octet <= 255:
+            raise IndexError('Invalid octet: %r!' % octet)
+        if 0 <= octet <= 127:       #   Legacy class 'A' classification.
+            return 8
+        elif 128 <= octet <= 191:   #   Legacy class 'B' classification.
+            return 16
+        elif 192 <= octet <= 223:   #   Legacy class 'C' classification.
+            return 24
+        elif 224 <= octet <= 239:   #   Multicast address range.
+            return 4
+        return 32                   #   Default.
+
+    if _is_str(abbrev_cidr):
+        if ':' in abbrev_cidr or abbrev_cidr == '':
+            return abbrev_cidr
+
+    try:
+        #   Single octet partial integer or string address.
+        i = int(abbrev_cidr)
+        return "%s.0.0.0/%s" % (i, classful_prefix(i))
+    except ValueError:
+        #   Multi octet partial string address with optional prefix.
+        if '/' in abbrev_cidr:
+            part_addr, prefix = abbrev_cidr.split('/', 1)
+
+            #   Check prefix for validity.
+            try:
+                if not 0 <= int(prefix) <= 32:
+                    raise ValueError('prefixlen in address %r out of range' \
+                        ' for IPv4!' % (abbrev_cidr,))
+            except ValueError:
+                return abbrev_cidr
+        else:
+            part_addr = abbrev_cidr
+            prefix = None
+
+        tokens = part_addr.split('.')
+        if len(tokens) > 4:
+            #   Not a recognisable format.
+            return abbrev_cidr
+        for i in range(4 - len(tokens)):
+            tokens.append('0')
+
+        if prefix is None:
+            try:
+                prefix = classful_prefix(tokens[0])
+            except ValueError:
+                return abbrev_cidr
+
+        return "%s/%s" % ('.'.join(tokens), prefix)
+    except (TypeError, IndexError):
+        #   Not a recognisable format.
+        return abbrev_cidr
+
+
+
+def cidr_merge(ip_addrs):
+    """
+    A function that accepts an iterable sequence of IP addresses and subnets
+    merging them into the smallest possible list of CIDRs. It merges adjacent
+    subnets where possible, those contained within others and also removes
+    any duplicates.
+
+    :param ip_addrs: an iterable sequence of IP addresses, subnets or ranges.
+
+    :return: a summarized list of `IPNetwork` objects.
+    """
+    # The algorithm is quite simple: For each CIDR we create an IP range.
+    # Sort them and merge when possible.  Afterwars split them again
+    # optimally.
+    if not hasattr(ip_addrs, '__iter__'):
+        raise ValueError('A sequence or iterator is expected!')
+
+    ranges = []
+
+    for ip in ip_addrs:
+        if isinstance(ip, (IPNetwork, IPRange)):
+            net = ip
+        else:
+            net = IPNetwork(ip)
+        # Since non-overlapping ranges are the common case, remember the original
+        ranges.append( (net.version, net.last, net.first, net) )
+
+    ranges.sort()
+    i = len(ranges) - 1
+    while i > 0:
+        if ranges[i][0] == ranges[i - 1][0] and ranges[i][2] - 1 <= ranges[i - 1][1]:
+            ranges[i - 1] = (ranges[i][0], ranges[i][1], min(ranges[i - 1][2], ranges[i][2]))
+            del ranges[i]
+        i -= 1
+    merged = []
+    for range_tuple in ranges:
+        # If this range wasn't merged we can simply use the old cidr.
+        if len(range_tuple) == 4:
+            original = range_tuple[3]
+            if isinstance(original, IPRange):
+                merged.extend(original.cidrs())
+            else:
+                merged.append(original)
+        else:
+            version = range_tuple[0]
+            range_start = IPAddress(range_tuple[2], version=version)
+            range_stop = IPAddress(range_tuple[1], version=version)
+            merged.extend(iprange_to_cidrs(range_start, range_stop))
+    return merged
+
+
+def cidr_exclude(target, exclude):
+    """
+    Removes an exclude IP address or subnet from target IP subnet.
+
+    :param target: the target IP address or subnet to be divided up.
+
+    :param exclude: the IP address or subnet to be removed from target.
+
+    :return: list of `IPNetwork` objects remaining after exclusion.
+    """
+    left, _, right = cidr_partition(target, exclude)
+
+    return left + right
+
+def cidr_partition(target, exclude):
+    """
+    Partitions a target IP subnet on an exclude IP address.
+
+    :param target: the target IP address or subnet to be divided up.
+
+    :param exclude: the IP address or subnet to partition on
+
+    :return: list of `IPNetwork` objects before, the partition and after, sorted.
+
+    Adding the three lists returns the equivalent of the original subnet.
+    """
+
+    target = IPNetwork(target)
+    exclude = IPNetwork(exclude)
+
+    if exclude.last < target.first:
+        #   Exclude subnet's upper bound address less than target
+        #   subnet's lower bound.
+        return [], [], [target.cidr]
+    elif target.last < exclude.first:
+        #   Exclude subnet's lower bound address greater than target
+        #   subnet's upper bound.
+        return [target.cidr], [], []
+
+    if target.prefixlen >= exclude.prefixlen:
+        # Exclude contains the target
+        return [], [target], []
+
+    left = []
+    right = []
+
+    new_prefixlen = target.prefixlen + 1
+    # Some @properties that are expensive to get and don't change below.
+    target_module_width = target._module.width
+
+    target_first = target.first
+    version = exclude.version
+    i_lower = target_first
+    i_upper = target_first + (2 ** (target_module_width - new_prefixlen))
+
+    while exclude.prefixlen >= new_prefixlen:
+        if exclude.first >= i_upper:
+            left.append(IPNetwork((i_lower, new_prefixlen), version=version))
+            matched = i_upper
+        else:
+            right.append(IPNetwork((i_upper, new_prefixlen), version=version))
+            matched = i_lower
+
+        new_prefixlen += 1
+
+        if new_prefixlen > target_module_width:
+            break
+
+        i_lower = matched
+        i_upper = matched + (2 ** (target_module_width - new_prefixlen))
+
+    return left, [exclude], right[::-1]
+
+
+def spanning_cidr(ip_addrs):
+    """
+    Function that accepts a sequence of IP addresses and subnets returning
+    a single `IPNetwork` subnet that is large enough to span the lower and
+    upper bound IP addresses with a possible overlap on either end.
+
+    :param ip_addrs: sequence of IP addresses and subnets.
+
+    :return: a single spanning `IPNetwork` subnet.
+    """
+    ip_addrs_iter = iter(ip_addrs)
+    try:
+        network_a = IPNetwork(_iter_next(ip_addrs_iter))
+        network_b = IPNetwork(_iter_next(ip_addrs_iter))
+    except StopIteration:
+        raise ValueError('IP sequence must contain at least 2 elements!')
+
+    if network_a < network_b:
+        min_network = network_a
+        max_network = network_b
+    else:
+        min_network = network_b
+        max_network = network_a
+
+    for ip in ip_addrs_iter:
+        network = IPNetwork(ip)
+        if network < min_network:
+            min_network = network
+        if network > max_network:
+            max_network = network
+
+    if min_network.version != max_network.version:
+        raise TypeError('IP sequence cannot contain both IPv4 and IPv6!')
+
+    ipnum = max_network.last
+    prefixlen = max_network.prefixlen
+    lowest_ipnum = min_network.first
+    width = max_network._module.width
+
+    while prefixlen > 0 and ipnum > lowest_ipnum:
+        prefixlen -= 1
+        ipnum &= -(1<<(width-prefixlen))
+
+    return IPNetwork( (ipnum, prefixlen), version=min_network.version )
+
+
+def iter_iprange(start, end, step=1):
+    """
+    A generator that produces IPAddress objects between an arbitrary start
+    and stop IP address with intervals of step between them. Sequences
+    produce are inclusive of boundary IPs.
+
+    :param start: start IP address.
+
+    :param end: end IP address.
+
+    :param step: (optional) size of step between IP addresses. Default: 1
+
+    :return: an iterator of one or more `IPAddress` objects.
+    """
+    start = IPAddress(start)
+    end = IPAddress(end)
+
+    if start.version != end.version:
+        raise TypeError('start and stop IP versions do not match!')
+    version = start.version
+
+    step = int(step)
+    if step == 0:
+        raise ValueError('step argument cannot be zero')
+
+    #   We don't need objects from here, just integers.
+    start = int(start)
+    stop = int(end)
+
+    negative_step = False
+
+    if step < 0:
+        negative_step = True
+
+    index = start - step
+    while True:
+        index += step
+        if negative_step:
+            if not index >= stop:
+                break
+        else:
+            if not index <= stop:
+                break
+        yield IPAddress(index, version)
+
+
+
+def iprange_to_cidrs(start, end):
+    """
+    A function that accepts an arbitrary start and end IP address or subnet
+    and returns a list of CIDR subnets that fit exactly between the boundaries
+    of the two with no overlap.
+
+    :param start: the start IP address or subnet.
+
+    :param end: the end IP address or subnet.
+
+    :return: a list of one or more IP addresses and subnets.
+    """
+    cidr_list = []
+
+    start = IPNetwork(start)
+    end = IPNetwork(end)
+
+    iprange = [start.first, end.last]
+
+    #   Get spanning CIDR covering both addresses.
+    cidr_span = spanning_cidr([start, end])
+    width = start._module.width
+
+    if cidr_span.first < iprange[0]:
+        exclude = IPNetwork((iprange[0]-1, width), version=start.version)
+        cidr_list = cidr_partition(cidr_span, exclude)[2]
+        cidr_span = cidr_list.pop()
+    if cidr_span.last > iprange[1]:
+        exclude = IPNetwork((iprange[1]+1, width), version=start.version)
+        cidr_list += cidr_partition(cidr_span, exclude)[0]
+    else:
+        cidr_list.append(cidr_span)
+
+    return cidr_list
+
+
+def smallest_matching_cidr(ip, cidrs):
+    """
+    Matches an IP address or subnet against a given sequence of IP addresses
+    and subnets.
+
+    :param ip: a single IP address or subnet.
+
+    :param cidrs: a sequence of IP addresses and/or subnets.
+
+    :return: the smallest (most specific) matching IPAddress or IPNetwork
+        object from the provided sequence, None if there was no match.
+    """
+    match = None
+
+    if not hasattr(cidrs, '__iter__'):
+        raise TypeError('IP address/subnet sequence expected, not %r!'
+            % (cidrs,))
+
+    ip = IPAddress(ip)
+    for cidr in sorted([IPNetwork(cidr) for cidr in cidrs]):
+        if ip in cidr:
+            match = cidr
+        else:
+            if match is not None and cidr.network not in match:
+                break
+
+    return match
+
+
+def largest_matching_cidr(ip, cidrs):
+    """
+    Matches an IP address or subnet against a given sequence of IP addresses
+    and subnets.
+
+    :param ip: a single IP address or subnet.
+
+    :param cidrs: a sequence of IP addresses and/or subnets.
+
+    :return: the largest (least specific) matching IPAddress or IPNetwork
+        object from the provided sequence, None if there was no match.
+    """
+    match = None
+
+    if not hasattr(cidrs, '__iter__'):
+        raise TypeError('IP address/subnet sequence expected, not %r!'
+            % (cidrs,))
+
+    ip = IPAddress(ip)
+    for cidr in sorted([IPNetwork(cidr) for cidr in cidrs]):
+        if ip in cidr:
+            match = cidr
+            break
+
+    return match
+
+
+def all_matching_cidrs(ip, cidrs):
+    """
+    Matches an IP address or subnet against a given sequence of IP addresses
+    and subnets.
+
+    :param ip: a single IP address.
+
+    :param cidrs: a sequence of IP addresses and/or subnets.
+
+    :return: all matching IPAddress and/or IPNetwork objects from the provided
+        sequence, an empty list if there was no match.
+    """
+    matches = []
+
+    if not hasattr(cidrs, '__iter__'):
+        raise TypeError('IP address/subnet sequence expected, not %r!'
+            % (cidrs,))
+
+    ip = IPAddress(ip)
+    for cidr in sorted([IPNetwork(cidr) for cidr in cidrs]):
+        if ip in cidr:
+            matches.append(cidr)
+        else:
+            if matches and cidr.network not in matches[-1]:
+                break
+
+    return matches
+
+#-----------------------------------------------------------------------------
+#   Cached IPv4 address range lookups.
+#-----------------------------------------------------------------------------
+IPV4_LOOPBACK  = IPNetwork('127.0.0.0/8')    #   Loopback addresses (RFC 990)
+
+IPV4_PRIVATE_USE = [
+    IPNetwork('10.0.0.0/8'),        #   Class A private network local communication (RFC 1918)
+    IPNetwork('172.16.0.0/12'),     #   Private network - local communication (RFC 1918)
+    IPNetwork('192.168.0.0/16'),    #  Class B private network local communication (RFC 1918)
+]
+
+IPV4_PRIVATEISH = tuple(IPV4_PRIVATE_USE) + (
+    IPNetwork('100.64.0.0/10'),     #   Carrier grade NAT (RFC 6598)
+    IPNetwork('192.0.0.0/24'),      #   IANA IPv4 Special Purpose Address Registry (RFC 5736)
+    # protocol assignments
+    
+    # benchmarking
+    IPNetwork('198.18.0.0/15'),     #  Testing of inter-network communications between subnets (RFC 2544)
+    IPRange('239.0.0.0', '239.255.255.255'),    #   Administrative Multicast
+)
+
+IPV4_LINK_LOCAL = IPNetwork('169.254.0.0/16')
+
+IPV4_MULTICAST = IPNetwork('224.0.0.0/4')
+
+IPV4_6TO4 = IPNetwork('192.88.99.0/24')    #   6to4 anycast relays (RFC 3068)
+
+IPV4_RESERVED = (
+    IPNetwork('0.0.0.0/8'),         #   Broadcast message (RFC 1700)
+    IPNetwork('192.0.2.0/24'),      #   TEST-NET examples and documentation (RFC 5737)
+    IPNetwork('240.0.0.0/4'),       #   Reserved for  multicast assignments (RFC 5771)
+    IPNetwork('198.51.100.0/24'),   #   TEST-NET-2 examples and documentation (RFC 5737)
+    IPNetwork('203.0.113.0/24'),    #   TEST-NET-3 examples and documentation (RFC 5737)
+
+    #   Reserved multicast
+    IPNetwork('233.252.0.0/24'),    #   Multicast test network
+    IPRange('234.0.0.0', '238.255.255.255'),
+    IPRange('225.0.0.0', '231.255.255.255'),
+) + (IPV4_LOOPBACK, IPV4_6TO4)
+
+IPV4_NOT_GLOBALLY_REACHABLE = [
+    IPNetwork(net) for net in [
+        '0.0.0.0/8',
+        '10.0.0.0/8',
+        '100.64.0.0/10',
+        '127.0.0.0/8',
+        '169.254.0.0/16',
+        '172.16.0.0/12',
+        '192.0.0.0/24',
+        '192.0.0.170/31',
+        '192.0.2.0/24',
+        '192.168.0.0/16',
+        '198.18.0.0/15',
+        '198.51.100.0/24',
+        '203.0.113.0/24',
+        '240.0.0.0/4',
+        '255.255.255.255/32',
+    ]
+]
+
+IPV4_NOT_GLOBALLY_REACHABLE_EXCEPTIONS = [
+    IPNetwork(net) for net in ['192.0.0.9/32', '192.0.0.10/32']
+]
+
+#-----------------------------------------------------------------------------
+#   Cached IPv6 address range lookups.
+#-----------------------------------------------------------------------------
+IPV6_LOOPBACK = IPNetwork('::1/128')
+
+IPV6_UNIQUE_LOCAL = IPNetwork('fc00::/7')
+
+IPV6_PRIVATEISH = (
+    IPV6_UNIQUE_LOCAL,
+    IPNetwork('fec0::/10'), #   Site Local Addresses (deprecated - RFC 3879)
+)
+
+IPV6_LINK_LOCAL = IPNetwork('fe80::/10')
+
+IPV6_MULTICAST = IPNetwork('ff00::/8')
+
+IPV6_RESERVED = (
+    IPNetwork('ff00::/12'), IPNetwork('::/8'),
+    IPNetwork('0100::/8'), IPNetwork('0200::/7'),
+    IPNetwork('0400::/6'), IPNetwork('0800::/5'),
+    IPNetwork('1000::/4'), IPNetwork('4000::/3'),
+    IPNetwork('6000::/3'), IPNetwork('8000::/3'),
+    IPNetwork('A000::/3'), IPNetwork('C000::/3'),
+    IPNetwork('E000::/4'), IPNetwork('F000::/5'),
+    IPNetwork('F800::/6'), IPNetwork('FE00::/9'),
+)
+
+IPV6_NOT_GLOBALLY_REACHABLE = [
+    IPNetwork(net)
+    for net in [
+        '::1/128',
+        '::/128',
+        '::ffff:0:0/96',
+        '64:ff9b:1::/48',
+        '100::/64',
+        '2001::/23',
+        '2001:db8::/32',
+        '2002::/16',
+        'fc00::/7',
+        'fe80::/10',
+    ]
+]
+
+IPV6_NOT_GLOBALLY_REACHABLE_EXCEPTIONS = [
+    IPNetwork(net)
+    for net in [
+        '2001:1::1/128',
+        '2001:1::2/128',
+        '2001:3::/32',
+        '2001:4:112::/48',
+        '2001:20::/28',
+        '2001:30::/28',
+]    ]