ip_int: An integer, the IP address.

            mask: The netmask.  Defaults to 32.

        Returns:

            An integer, the prefix length.

        """

        while mask:

            if ip_int & 1 == 1:

                break

            ip_int >>= 1

            mask -= 1

        return mask

    def _ip_string_from_prefix(self, prefixlen=None):

        """Turn a prefix length into a dotted decimal string.

        Args:

            prefixlen: An integer, the netmask prefix length.

        Returns:

            A string, the dotted decimal netmask string.

        """

        if not prefixlen:

            prefixlen = self._prefixlen

        return self._string_from_ip_int(self._ip_int_from_prefix(prefixlen))

    def iter_subnets(self, prefixlen_diff=1, new_prefix=None):

        """The subnets which join to make the current subnet.

        In the case that self contains only one IP

        (self._prefixlen == 32 for IPv4 or self._prefixlen == 128

        for IPv6), return a list with just ourself.

        Args:

            prefixlen_diff: An integer, the amount the prefix length

              should be increased by. This should not be set if

              new_prefix is also set.

            new_prefix: The desired new prefix length. This must be a

              larger number (smaller prefix) than the existing prefix.

              This should not be set if prefixlen_diff is also set.

        Returns:

            An iterator of IPv(4|6) objects.

        Raises:

            ValueError: The prefixlen_diff is too small or too large.

                OR

            prefixlen_diff and new_prefix are both set or new_prefix

              is a smaller number than the current prefix (smaller

              number means a larger network)

        """

        if self._prefixlen == self._max_prefixlen:

            yield self

            return

        if new_prefix is not None:

            if new_prefix < self._prefixlen:

                raise ValueError('new prefix must be longer')

            if prefixlen_diff != 1:

                raise ValueError('cannot set prefixlen_diff and new_prefix')

            prefixlen_diff = new_prefix - self._prefixlen

        if prefixlen_diff < 0:

            raise ValueError('prefix length diff must be > 0')

        new_prefixlen = self._prefixlen + prefixlen_diff

        if not self._is_valid_netmask(str(new_prefixlen)):

            raise ValueError(

                'prefix length diff %d is invalid for netblock %s' % (

                    new_prefixlen, str(self)))

        first = IPNetwork('%s/%s' % (str(self.network),

                                     str(self._prefixlen + prefixlen_diff)),

                         version=self._version)

        yield first

        current = first

        while True:

            broadcast = current.broadcast

            if broadcast == self.broadcast:

                return

            new_addr = IPAddress(int(broadcast) + 1, version=self._version)

            current = IPNetwork('%s/%s' % (str(new_addr), str(new_prefixlen)),

                                version=self._version)

            yield current

    def masked(self):

        """Return the network object with the host bits masked out."""

        return IPNetwork('%s/%d' % (self.network, self._prefixlen),

                         version=self._version)

    def subnet(self, prefixlen_diff=1, new_prefix=None):

        """Return a list of subnets, rather than an iterator."""

        return list(self.iter_subnets(prefixlen_diff, new_prefix))

    def supernet(self, prefixlen_diff=1, new_prefix=None):

        """The supernet containing the current network.

        Args:

            prefixlen_diff: An integer, the amount the prefix length of

              the network should be decreased by.  For example, given a

              /24 network and a prefixlen_diff of 3, a supernet with a

              /21 netmask is returned.

        Returns:

            An IPv4 network object.

        Raises:

            ValueError: If self.prefixlen - prefixlen_diff < 0. I.e., you have a

              negative prefix length.

                OR

            If prefixlen_diff and new_prefix are both set or new_prefix is a

              larger number than the current prefix (larger number means a

              smaller network)

        """

        if self._prefixlen == 0:

            return self

        if new_prefix is not None:

            if new_prefix > self._prefixlen:

                raise ValueError('new prefix must be shorter')

            if prefixlen_diff != 1:

                raise ValueError('cannot set prefixlen_diff and new_prefix')

            prefixlen_diff = self._prefixlen - new_prefix

        if self.prefixlen - prefixlen_diff < 0:

            raise ValueError(

                'current prefixlen is %d, cannot have a prefixlen_diff of %d' %

                (self.prefixlen, prefixlen_diff))

        return IPNetwork('%s/%s' % (str(self.network),

                                    str(self.prefixlen - prefixlen_diff)),

                         version=self._version)

    # backwards compatibility

    Subnet = subnet

    Supernet = supernet

    AddressExclude = address_exclude

    CompareNetworks = compare_networks

    Contains = __contains__

class _BaseV4(object):

    """Base IPv4 object.

    The following methods are used by IPv4 objects in both single IP

    addresses and networks.

    """

    # Equivalent to 255.255.255.255 or 32 bits of 1's.

    _ALL_ONES = (2 ** IPV4LENGTH) - 1

    _DECIMAL_DIGITS = frozenset('0123456789')

    def __init__(self, address):

        self._version = 4

        self._max_prefixlen = IPV4LENGTH

    def _explode_shorthand_ip_string(self):

        return str(self)

    def _ip_int_from_string(self, ip_str):

        """Turn the given IP string into an integer for comparison.

        Args:

            ip_str: A string, the IP ip_str.

        Returns:

            The IP ip_str as an integer.

        Raises:

            AddressValueError: if ip_str isn't a valid IPv4 Address.

        """

        octets = ip_str.split('.')

        if len(octets) != 4:

            raise AddressValueError(ip_str)

        packed_ip = 0

        for oc in octets:

            try:

                packed_ip = (packed_ip << 8) | self._parse_octet(oc)

            except ValueError:

                raise AddressValueError(ip_str)

        return packed_ip

    def _parse_octet(self, octet_str):

        """Convert a decimal octet into an integer.

        Args:

            octet_str: A string, the number to parse.

        Returns:

            The octet as an integer.

        Raises:

            ValueError: if the octet isn't strictly a decimal from [0..255].

        """

        # Whitelist the characters, since int() allows a lot of bizarre stuff.

        if not self._DECIMAL_DIGITS.issuperset(octet_str):

            raise ValueError

        octet_int = int(octet_str, 10)

        # Disallow leading zeroes, because no clear standard exists on

        # whether these should be interpreted as decimal or octal.

        if octet_int > 255 or (octet_str[0] == '0' and len(octet_str) > 1):

            raise ValueError

        return octet_int

    def _string_from_ip_int(self, ip_int):

        """Turns a 32-bit integer into dotted decimal notation.

        Args:

            ip_int: An integer, the IP address.

        Returns:

            The IP address as a string in dotted decimal notation.

        """

        octets = []

        for _ in xrange(4):

            octets.insert(0, str(ip_int & 0xFF))

            ip_int >>= 8

        return '.'.join(octets)

    @property

    def max_prefixlen(self):

        return self._max_prefixlen

    @property

    def packed(self):

        """The binary representation of this address."""

        return v4_int_to_packed(self._ip)

    @property

    def version(self):

        return self._version

    @property

    def is_reserved(self):

        """Test if the address is otherwise IETF reserved.

         Returns:

             A boolean, True if the address is within the

             reserved IPv4 Network range.

        """

        return self in IPv4Network('240.0.0.0/4')

    @property

    def is_private(self):

        """Test if this address is allocated for private networks.

        Returns:

            A boolean, True if the address is reserved per RFC 1918.

        """

        return (self in IPv4Network('10.0.0.0/8') or

                self in IPv4Network('172.16.0.0/12') or

                self in IPv4Network('192.168.0.0/16'))

    @property

    def is_multicast(self):

        """Test if the address is reserved for multicast use.

        Returns:

            A boolean, True if the address is multicast.

            See RFC 3171 for details.

        """

        return self in IPv4Network('224.0.0.0/4')

    @property

    def is_unspecified(self):

        """Test if the address is unspecified.

        Returns:

            A boolean, True if this is the unspecified address as defined in

            RFC 5735 3.

        """

        return self in IPv4Network('0.0.0.0')

    @property

    def is_loopback(self):

        """Test if the address is a loopback address.

        Returns:

            A boolean, True if the address is a loopback per RFC 3330.

        """

        return self in IPv4Network('127.0.0.0/8')

    @property

    def is_link_local(self):

        """Test if the address is reserved for link-local.

        Returns:

            A boolean, True if the address is link-local per RFC 3927.

        """

        return self in IPv4Network('169.254.0.0/16')

class IPv4Address(_BaseV4, _BaseIP):

    """Represent and manipulate single IPv4 Addresses."""

    def __init__(self, address):

        """

        Args:

            address: A string or integer representing the IP

              '192.168.1.1'

              Additionally, an integer can be passed, so

              IPv4Address('192.168.1.1') == IPv4Address(3232235777).

              or, more generally

              IPv4Address(int(IPv4Address('192.168.1.1'))) ==

                IPv4Address('192.168.1.1')

        Raises:

            AddressValueError: If ipaddr isn't a valid IPv4 address.

        """

        _BaseV4.__init__(self, address)

        # Efficient constructor from integer.

        if isinstance(address, (int, long)):

            self._ip = address

            if address < 0 or address > self._ALL_ONES:

                raise AddressValueError(address)

            return

        # Constructing from a packed address

        if isinstance(address, Bytes):

            try:

                self._ip, = struct.unpack('!I', address)

            except struct.error:

                raise AddressValueError(address)  # Wrong length.

            return

        # Assume input argument to be string or any object representation

        # which converts into a formatted IP string.

        addr_str = str(address)

        self._ip = self._ip_int_from_string(addr_str)

class IPv4Network(_BaseV4, _BaseNet):

    """This class represents and manipulates 32-bit IPv4 networks.

    Attributes: [examples for IPv4Network('1.2.3.4/27')]

        ._ip: 16909060

        .ip: IPv4Address('1.2.3.4')

        .network: IPv4Address('1.2.3.0')

        .hostmask: IPv4Address('0.0.0.31')

        .broadcast: IPv4Address('1.2.3.31')

        .netmask: IPv4Address('255.255.255.224')

        .prefixlen: 27

    """

    # the valid octets for host and netmasks. only useful for IPv4.

    _valid_mask_octets = set((255, 254, 252, 248, 240, 224, 192, 128, 0))

    def __init__(self, address, strict=False):

        """Instantiate a new IPv4 network object.

        Args:

            address: A string or integer representing the IP [& network].

              '192.168.1.1/24'

              '192.168.1.1/255.255.255.0'

              '192.168.1.1/0.0.0.255'

              are all functionally the same in IPv4. Similarly,

              '192.168.1.1'

              '192.168.1.1/255.255.255.255'

              '192.168.1.1/32'

              provide a subnetmask will create an object with a mask of /32.

              If the mask (portion after the / in the argument) is given in

              dotted quad form, it is treated as a netmask if it starts with a

              non-zero field (e.g. /255.0.0.0 == /8) and as a hostmask if it

              starts with a zero field (e.g. 0.255.255.255 == /8), with the

              single exception of an all-zero mask which is treated as a

              netmask == /0. If no mask is given, a default of /32 is used.

              Additionally, an integer can be passed, so

              IPv4Network('192.168.1.1') == IPv4Network(3232235777).

              or, more generally

              IPv4Network(int(IPv4Network('192.168.1.1'))) ==

                IPv4Network('192.168.1.1')

            strict: A boolean. If true, ensure that we have been passed

              A true network address, eg, 192.168.1.0/24 and not an

              IP address on a network, eg, 192.168.1.1/24.

        Raises:

            AddressValueError: If ipaddr isn't a valid IPv4 address.

            NetmaskValueError: If the netmask isn't valid for

              an IPv4 address.

            ValueError: If strict was True and a network address was not

              supplied.

        """

        _BaseNet.__init__(self, address)

        _BaseV4.__init__(self, address)

        # Constructing from an integer or packed bytes.

        if isinstance(address, (int, long, Bytes)):

            self.ip = IPv4Address(address)

            self._ip = self.ip._ip

            self._prefixlen = self._max_prefixlen

            self.netmask = IPv4Address(self._ALL_ONES)

            return

        # Assume input argument to be string or any object representation

        # which converts into a formatted IP prefix string.

        addr = str(address).split('/')

        if len(addr) > 2:

            raise AddressValueError(address)

        self._ip = self._ip_int_from_string(addr[0])

        self.ip = IPv4Address(self._ip)

        if len(addr) == 2:

            mask = addr[1].split('.')

            if len(mask) == 4:

                # We have dotted decimal netmask.

                if self._is_valid_netmask(addr[1]):

                    self.netmask = IPv4Address(self._ip_int_from_string(

                            addr[1]))

                elif self._is_hostmask(addr[1]):

                    self.netmask = IPv4Address(

                        self._ip_int_from_string(addr[1]) ^ self._ALL_ONES)

                else:

                    raise NetmaskValueError('%s is not a valid netmask'

                                                     % addr[1])

                self._prefixlen = self._prefix_from_ip_int(int(self.netmask))

            else:

                # We have a netmask in prefix length form.

                if not self._is_valid_netmask(addr[1]):

                    raise NetmaskValueError(addr[1])

                self._prefixlen = int(addr[1])

                self.netmask = IPv4Address(self._ip_int_from_prefix(

                    self._prefixlen))

        else:

            self._prefixlen = self._max_prefixlen

            self.netmask = IPv4Address(self._ip_int_from_prefix(

                self._prefixlen))

        if strict:

            if self.ip != self.network:

                raise ValueError('%s has host bits set' %

                                 self.ip)

        if self._prefixlen == (self._max_prefixlen - 1):

            self.iterhosts = self.__iter__

    def _is_hostmask(self, ip_str):

        """Test if the IP string is a hostmask (rather than a netmask).

        Args:

            ip_str: A string, the potential hostmask.

        Returns:

            A boolean, True if the IP string is a hostmask.

        """

        bits = ip_str.split('.')

        try:

            parts = [int(x) for x in bits if int(x) in self._valid_mask_octets]

        except ValueError:

            return False

        if len(parts) != len(bits):

            return False

        if parts[0] < parts[-1]:

            return True

        return False

    def _is_valid_netmask(self, netmask):

        """Verify that the netmask is valid.

        Args:

            netmask: A string, either a prefix or dotted decimal

              netmask.

        Returns:

            A boolean, True if the prefix represents a valid IPv4

            netmask.

        """

        mask = netmask.split('.')

        if len(mask) == 4:

            if [x for x in mask if int(x) not in self._valid_mask_octets]:

                return False

            if [y for idx, y in enumerate(mask) if idx > 0 and

                y > mask[idx - 1]]:

                return False

            return True

        try:

            netmask = int(netmask)

        except ValueError:

            return False

        return 0 <= netmask <= self._max_prefixlen

    # backwards compatibility

    IsRFC1918 = lambda self: self.is_private

    IsMulticast = lambda self: self.is_multicast

    IsLoopback = lambda self: self.is_loopback

    IsLinkLocal = lambda self: self.is_link_local

class _BaseV6(object):

    """Base IPv6 object.

    The following methods are used by IPv6 objects in both single IP

    addresses and networks.

    """

    _ALL_ONES = (2 ** IPV6LENGTH) - 1

    _HEXTET_COUNT = 8

    _HEX_DIGITS = frozenset('0123456789ABCDEFabcdef')

    def __init__(self, address):

        self._version = 6

        self._max_prefixlen = IPV6LENGTH

    def _ip_int_from_string(self, ip_str):

        """Turn an IPv6 ip_str into an integer.

        Args:

            ip_str: A string, the IPv6 ip_str.

        Returns:

            A long, the IPv6 ip_str.

        Raises:

            AddressValueError: if ip_str isn't a valid IPv6 Address.

        """

        parts = ip_str.split(':')

        # An IPv6 address needs at least 2 colons (3 parts).

        if len(parts) < 3:

            raise AddressValueError(ip_str)

        # If the address has an IPv4-style suffix, convert it to hexadecimal.

        if '.' in parts[-1]:

            ipv4_int = IPv4Address(parts.pop())._ip

            parts.append('%x' % ((ipv4_int >> 16) & 0xFFFF))

            parts.append('%x' % (ipv4_int & 0xFFFF))

        # An IPv6 address can't have more than 8 colons (9 parts).

        if len(parts) > self._HEXTET_COUNT + 1:

            raise AddressValueError(ip_str)

        # Disregarding the endpoints, find '::' with nothing in between.

        # This indicates that a run of zeroes has been skipped.

        try:

            skip_index, = (

                [i for i in xrange(1, len(parts) - 1) if not parts[i]] or

                [None])

        except ValueError:

            # Can't have more than one '::'

            raise AddressValueError(ip_str)

        # parts_hi is the number of parts to copy from above/before the '::'

        # parts_lo is the number of parts to copy from below/after the '::'

        if skip_index is not None:

            # If we found a '::', then check if it also covers the endpoints.

            parts_hi = skip_index

            parts_lo = len(parts) - skip_index - 1

            if not parts[0]:

                parts_hi -= 1

                if parts_hi:

                    raise AddressValueError(ip_str)  # ^: requires ^::

            if not parts[-1]:

                parts_lo -= 1

                if parts_lo:

                    raise AddressValueError(ip_str)  # :$ requires ::$

            parts_skipped = self._HEXTET_COUNT - (parts_hi + parts_lo)

            if parts_skipped < 1:

                raise AddressValueError(ip_str)

        else:

            # Otherwise, allocate the entire address to parts_hi.  The endpoints

            # could still be empty, but _parse_hextet() will check for that.

            if len(parts) != self._HEXTET_COUNT:

                raise AddressValueError(ip_str)

            parts_hi = len(parts)

            parts_lo = 0

            parts_skipped = 0

        try:

            # Now, parse the hextets into a 128-bit integer.

            ip_int = 0L

            for i in xrange(parts_hi):

                ip_int <<= 16

                ip_int |= self._parse_hextet(parts[i])

            ip_int <<= 16 * parts_skipped

            for i in xrange(-parts_lo, 0):

                ip_int <<= 16

                ip_int |= self._parse_hextet(parts[i])

            return ip_int

        except ValueError:

            raise AddressValueError(ip_str)

    def _parse_hextet(self, hextet_str):

        """Convert an IPv6 hextet string into an integer.

        Args:

            hextet_str: A string, the number to parse.

        Returns:

            The hextet as an integer.

        Raises:

            ValueError: if the input isn't strictly a hex number from [0..FFFF].

        """

        # Whitelist the characters, since int() allows a lot of bizarre stuff.

        if not self._HEX_DIGITS.issuperset(hextet_str):

            raise ValueError

        if len(hextet_str) > 4:

            raise ValueError

        hextet_int = int(hextet_str, 16)

        if hextet_int > 0xFFFF:

            raise ValueError

        return hextet_int

    def _compress_hextets(self, hextets):

        """Compresses a list of hextets.

        Compresses a list of strings, replacing the longest continuous

        sequence of "0" in the list with "" and adding empty strings at

        the beginning or at the end of the string such that subsequently

        calling ":".join(hextets) will produce the compressed version of

        the IPv6 address.

        Args:

            hextets: A list of strings, the hextets to compress.

        Returns:

            A list of strings.

        """

        best_doublecolon_start = -1

        best_doublecolon_len = 0

        doublecolon_start = -1

        doublecolon_len = 0

        for index in range(len(hextets)):

            if hextets[index] == '0':

                doublecolon_len += 1

                if doublecolon_start == -1:

                    # Start of a sequence of zeros.

                    doublecolon_start = index

                if doublecolon_len > best_doublecolon_len:

                    # This is the longest sequence of zeros so far.

                    best_doublecolon_len = doublecolon_len

                    best_doublecolon_start = doublecolon_start

            else:

                doublecolon_len = 0

                doublecolon_start = -1

        if best_doublecolon_len > 1:

            best_doublecolon_end = (best_doublecolon_start +

                                    best_doublecolon_len)

            # For zeros at the end of the address.

            if best_doublecolon_end == len(hextets):

                hextets += ['']

            hextets[best_doublecolon_start:best_doublecolon_end] = ['']

            # For zeros at the beginning of the address.

            if best_doublecolon_start == 0:

                hextets = [''] + hextets

        return hextets

    def _string_from_ip_int(self, ip_int=None):

        """Turns a 128-bit integer into hexadecimal notation.

        Args:

            ip_int: An integer, the IP address.

        Returns:

            A string, the hexadecimal representation of the address.

        Raises:

            ValueError: The address is bigger than 128 bits of all ones.

        """

        if not ip_int and ip_int != 0:

            ip_int = int(self._ip)

        if ip_int > self._ALL_ONES:

            raise ValueError('IPv6 address is too large')

        hex_str = '%032x' % ip_int

        hextets = []

        for x in range(0, 32, 4):

            hextets.append('%x' % int(hex_str[x:x + 4], 16))

        hextets = self._compress_hextets(hextets)

        return ':'.join(hextets)

    def _explode_shorthand_ip_string(self):

        """Expand a shortened IPv6 address.

        Args:

            ip_str: A string, the IPv6 address.

        Returns:

            A string, the expanded IPv6 address.

        """

        if isinstance(self, _BaseNet):

            ip_str = str(self.ip)

        else:

            ip_str = str(self)

        ip_int = self._ip_int_from_string(ip_str)

        parts = []

        for i in xrange(self._HEXTET_COUNT):

            parts.append('%04x' % (ip_int & 0xFFFF))

            ip_int >>= 16

        parts.reverse()

        if isinstance(self, _BaseNet):

            return '%s/%d' % (':'.join(parts), self.prefixlen)

        return ':'.join(parts)

    @property

    def max_prefixlen(self):

        return self._max_prefixlen

    @property

    def packed(self):

        """The binary representation of this address."""

        return v6_int_to_packed(self._ip)

    @property

    def version(self):

        return self._version

    @property

    def is_multicast(self):

        """Test if the address is reserved for multicast use.

        Returns:

            A boolean, True if the address is a multicast address.

            See RFC 2373 2.7 for details.

        """

        return self in IPv6Network('ff00::/8')

    @property

    def is_reserved(self):

        """Test if the address is otherwise IETF reserved.

        Returns:

            A boolean, True if the address is within one of the

            reserved IPv6 Network ranges.