ipaddress.py 69.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12
# Copyright 2007 Google Inc.
#  Licensed to PSF under a Contributor Agreement.

"""A fast, lightweight IPv4/IPv6 manipulation library in Python.

This library is used to create/poke/manipulate IPv4 and IPv6 addresses
and networks.

"""

__version__ = '1.0'

13

14
import functools
15

16 17 18 19 20 21 22 23 24 25 26
IPV4LENGTH = 32
IPV6LENGTH = 128

class AddressValueError(ValueError):
    """A Value Error related to the address."""


class NetmaskValueError(ValueError):
    """A Value Error related to the netmask."""


27
def ip_address(address):
28 29 30 31 32 33 34 35 36 37 38
    """Take an IP string/int and return an object of the correct type.

    Args:
        address: A string or integer, the IP address.  Either IPv4 or
          IPv6 addresses may be supplied; integers less than 2**32 will
          be considered to be IPv4 by default.

    Returns:
        An IPv4Address or IPv6Address object.

    Raises:
39
        ValueError: if the *address* passed isn't either a v4 or a v6
40
          address
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56

    """
    try:
        return IPv4Address(address)
    except (AddressValueError, NetmaskValueError):
        pass

    try:
        return IPv6Address(address)
    except (AddressValueError, NetmaskValueError):
        pass

    raise ValueError('%r does not appear to be an IPv4 or IPv6 address' %
                     address)


57
def ip_network(address, strict=True):
58 59 60 61 62 63 64 65 66 67 68 69
    """Take an IP string/int and return an object of the correct type.

    Args:
        address: A string or integer, the IP network.  Either IPv4 or
          IPv6 networks may be supplied; integers less than 2**32 will
          be considered to be IPv4 by default.

    Returns:
        An IPv4Network or IPv6Network object.

    Raises:
        ValueError: if the string passed isn't either a v4 or a v6
70
          address. Or if the network has host bits set.
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86

    """
    try:
        return IPv4Network(address, strict)
    except (AddressValueError, NetmaskValueError):
        pass

    try:
        return IPv6Network(address, strict)
    except (AddressValueError, NetmaskValueError):
        pass

    raise ValueError('%r does not appear to be an IPv4 or IPv6 network' %
                     address)


87
def ip_interface(address):
88 89 90 91 92 93 94 95
    """Take an IP string/int and return an object of the correct type.

    Args:
        address: A string or integer, the IP address.  Either IPv4 or
          IPv6 addresses may be supplied; integers less than 2**32 will
          be considered to be IPv4 by default.

    Returns:
96
        An IPv4Interface or IPv6Interface object.
97 98 99

    Raises:
        ValueError: if the string passed isn't either a v4 or a v6
100
          address.
101 102 103 104 105

    Notes:
        The IPv?Interface classes describe an Address on a particular
        Network, so they're basically a combination of both the Address
        and Network classes.
106

107 108 109 110 111 112 113 114 115 116 117
    """
    try:
        return IPv4Interface(address)
    except (AddressValueError, NetmaskValueError):
        pass

    try:
        return IPv6Interface(address)
    except (AddressValueError, NetmaskValueError):
        pass

118
    raise ValueError('%r does not appear to be an IPv4 or IPv6 interface' %
119 120 121 122
                     address)


def v4_int_to_packed(address):
123
    """Represent an address as 4 packed bytes in network (big-endian) order.
124 125 126 127 128

    Args:
        address: An integer representation of an IPv4 IP address.

    Returns:
129
        The integer address packed as 4 bytes in network (big-endian) order.
130 131

    Raises:
132 133
        ValueError: If the integer is negative or too large to be an
          IPv4 IP address.
134

135
    """
136
    try:
137
        return address.to_bytes(4, 'big')
138
    except OverflowError:
139
        raise ValueError("Address negative or too large for IPv4")
140 141 142


def v6_int_to_packed(address):
143
    """Represent an address as 16 packed bytes in network (big-endian) order.
144 145

    Args:
146
        address: An integer representation of an IPv6 IP address.
147 148

    Returns:
149
        The integer address packed as 16 bytes in network (big-endian) order.
150

151
    """
152
    try:
153
        return address.to_bytes(16, 'big')
154
    except OverflowError:
155
        raise ValueError("Address negative or too large for IPv6")
156 157


158 159 160 161 162 163 164
def _split_optional_netmask(address):
    """Helper to split the netmask and raise AddressValueError if needed"""
    addr = str(address).split('/')
    if len(addr) > 2:
        raise AddressValueError("Only one '/' permitted in %r" % address)
    return addr

165

166
def _find_address_range(addresses):
167
    """Find a sequence of sorted deduplicated IPv#Address.
168 169

    Args:
170
        addresses: a list of IPv#Address objects.
171

172 173
    Yields:
        A tuple containing the first and last IP addresses in the sequence.
174 175

    """
176 177 178 179 180 181 182 183
    it = iter(addresses)
    first = last = next(it)
    for ip in it:
        if ip._ip != last._ip + 1:
            yield first, last
            first = ip
        last = ip
    yield first, last
184

185

186 187 188 189 190 191 192 193 194 195 196 197 198
def _count_righthand_zero_bits(number, bits):
    """Count the number of zero bits on the right hand side.

    Args:
        number: an integer.
        bits: maximum number of bits to count.

    Returns:
        The number of zero bits on the right hand side of the number.

    """
    if number == 0:
        return bits
199
    return min(bits, (~number & (number-1)).bit_length())
200 201 202 203 204 205


def summarize_address_range(first, last):
    """Summarize a network range given the first and last IP addresses.

    Example:
206 207 208
        >>> list(summarize_address_range(IPv4Address('192.0.2.0'),
        ...                              IPv4Address('192.0.2.130')))
        ...                                #doctest: +NORMALIZE_WHITESPACE
209
        [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'),
210
         IPv4Network('192.0.2.130/32')]
211 212 213 214 215 216 217 218 219 220 221 222 223 224

    Args:
        first: the first IPv4Address or IPv6Address in the range.
        last: the last IPv4Address or IPv6Address in the range.

    Returns:
        An iterator of the summarized IPv(4|6) network objects.

    Raise:
        TypeError:
            If the first and last objects are not IP addresses.
            If the first and last objects are not the same version.
        ValueError:
            If the last object is not greater than the first.
225
            If the version of the first address is not 4 or 6.
226 227

    """
228 229
    if (not (isinstance(first, _BaseAddress) and
             isinstance(last, _BaseAddress))):
230 231 232
        raise TypeError('first and last must be IP addresses, not networks')
    if first.version != last.version:
        raise TypeError("%s and %s are not of the same version" % (
233
                         first, last))
234 235 236 237 238 239 240 241 242 243 244 245 246 247
    if first > last:
        raise ValueError('last IP address must be greater than first')

    if first.version == 4:
        ip = IPv4Network
    elif first.version == 6:
        ip = IPv6Network
    else:
        raise ValueError('unknown IP version')

    ip_bits = first._max_prefixlen
    first_int = first._ip
    last_int = last._ip
    while first_int <= last_int:
248 249
        nbits = min(_count_righthand_zero_bits(first_int, ip_bits),
                    (last_int - first_int + 1).bit_length() - 1)
250
        net = ip((first_int, ip_bits - nbits))
251
        yield net
252 253
        first_int += 1 << nbits
        if first_int - 1 == ip._ALL_ONES:
254 255
            break

256

257
def _collapse_addresses_internal(addresses):
258 259 260 261 262 263 264 265 266
    """Loops through the addresses, collapsing concurrent netblocks.

    Example:

        ip1 = IPv4Network('192.0.2.0/26')
        ip2 = IPv4Network('192.0.2.64/26')
        ip3 = IPv4Network('192.0.2.128/26')
        ip4 = IPv4Network('192.0.2.192/26')

267
        _collapse_addresses_internal([ip1, ip2, ip3, ip4]) ->
268 269 270 271 272 273 274 275 276 277 278 279 280
          [IPv4Network('192.0.2.0/24')]

        This shouldn't be called directly; it is called via
          collapse_addresses([]).

    Args:
        addresses: A list of IPv4Network's or IPv6Network's

    Returns:
        A list of IPv4Network's or IPv6Network's depending on what we were
        passed.

    """
281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
    # First merge
    to_merge = list(addresses)
    subnets = {}
    while to_merge:
        net = to_merge.pop()
        supernet = net.supernet()
        existing = subnets.get(supernet)
        if existing is None:
            subnets[supernet] = net
        elif existing != net:
            # Merge consecutive subnets
            del subnets[supernet]
            to_merge.append(supernet)
    # Then iterate over resulting networks, skipping subsumed subnets
    last = None
    for net in sorted(subnets.values()):
        if last is not None:
            # Since they are sorted, last.network_address <= net.network_address
            # is a given.
            if last.broadcast_address >= net.broadcast_address:
                continue
        yield net
        last = net
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332


def collapse_addresses(addresses):
    """Collapse a list of IP objects.

    Example:
        collapse_addresses([IPv4Network('192.0.2.0/25'),
                            IPv4Network('192.0.2.128/25')]) ->
                           [IPv4Network('192.0.2.0/24')]

    Args:
        addresses: An iterator of IPv4Network or IPv6Network objects.

    Returns:
        An iterator of the collapsed IPv(4|6)Network objects.

    Raises:
        TypeError: If passed a list of mixed version objects.

    """
    addrs = []
    ips = []
    nets = []

    # split IP addresses and networks
    for ip in addresses:
        if isinstance(ip, _BaseAddress):
            if ips and ips[-1]._version != ip._version:
                raise TypeError("%s and %s are not of the same version" % (
333
                                 ip, ips[-1]))
334 335 336 337
            ips.append(ip)
        elif ip._prefixlen == ip._max_prefixlen:
            if ips and ips[-1]._version != ip._version:
                raise TypeError("%s and %s are not of the same version" % (
338
                                 ip, ips[-1]))
339 340 341 342 343 344 345
            try:
                ips.append(ip.ip)
            except AttributeError:
                ips.append(ip.network_address)
        else:
            if nets and nets[-1]._version != ip._version:
                raise TypeError("%s and %s are not of the same version" % (
346
                                 ip, nets[-1]))
347 348
            nets.append(ip)

349 350
    # sort and dedup
    ips = sorted(set(ips))
351

352
    # find consecutive address ranges in the sorted sequence and summarize them
353 354 355
    if ips:
        for first, last in _find_address_range(ips):
            addrs.extend(summarize_address_range(first, last))
356

357
    return _collapse_addresses_internal(addrs + nets)
358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384


def get_mixed_type_key(obj):
    """Return a key suitable for sorting between networks and addresses.

    Address and Network objects are not sortable by default; they're
    fundamentally different so the expression

        IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')

    doesn't make any sense.  There are some times however, where you may wish
    to have ipaddress sort these for you anyway. If you need to do this, you
    can use this function as the key= argument to sorted().

    Args:
      obj: either a Network or Address object.
    Returns:
      appropriate key.

    """
    if isinstance(obj, _BaseNetwork):
        return obj._get_networks_key()
    elif isinstance(obj, _BaseAddress):
        return obj._get_address_key()
    return NotImplemented


385
class _IPAddressBase:
386 387 388

    """The mother class."""

389 390
    __slots__ = ()

391 392 393 394 395 396 397 398 399 400
    @property
    def exploded(self):
        """Return the longhand version of the IP address as a string."""
        return self._explode_shorthand_ip_string()

    @property
    def compressed(self):
        """Return the shorthand version of the IP address as a string."""
        return str(self)

401 402 403 404 405 406 407 408 409 410 411
    @property
    def reverse_pointer(self):
        """The name of the reverse DNS pointer for the IP address, e.g.:
            >>> ipaddress.ip_address("127.0.0.1").reverse_pointer
            '1.0.0.127.in-addr.arpa'
            >>> ipaddress.ip_address("2001:db8::1").reverse_pointer
            '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa'

        """
        return self._reverse_pointer()

412 413 414 415 416
    @property
    def version(self):
        msg = '%200s has no version specified' % (type(self),)
        raise NotImplementedError(msg)

417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432
    def _check_int_address(self, address):
        if address < 0:
            msg = "%d (< 0) is not permitted as an IPv%d address"
            raise AddressValueError(msg % (address, self._version))
        if address > self._ALL_ONES:
            msg = "%d (>= 2**%d) is not permitted as an IPv%d address"
            raise AddressValueError(msg % (address, self._max_prefixlen,
                                           self._version))

    def _check_packed_address(self, address, expected_len):
        address_len = len(address)
        if address_len != expected_len:
            msg = "%r (len %d != %d) is not permitted as an IPv%d address"
            raise AddressValueError(msg % (address, address_len,
                                           expected_len, self._version))

433 434
    @classmethod
    def _ip_int_from_prefix(cls, prefixlen):
435
        """Turn the prefix length into a bitwise netmask
436 437 438 439 440 441 442 443

        Args:
            prefixlen: An integer, the prefix length.

        Returns:
            An integer.

        """
444
        return cls._ALL_ONES ^ (cls._ALL_ONES >> prefixlen)
445

446 447
    @classmethod
    def _prefix_from_ip_int(cls, ip_int):
448
        """Return prefix length from the bitwise netmask.
449 450

        Args:
451
            ip_int: An integer, the netmask in expanded bitwise format
452 453 454 455 456 457 458 459

        Returns:
            An integer, the prefix length.

        Raises:
            ValueError: If the input intermingles zeroes & ones
        """
        trailing_zeroes = _count_righthand_zero_bits(ip_int,
460 461
                                                     cls._max_prefixlen)
        prefixlen = cls._max_prefixlen - trailing_zeroes
462 463 464
        leading_ones = ip_int >> trailing_zeroes
        all_ones = (1 << prefixlen) - 1
        if leading_ones != all_ones:
465
            byteslen = cls._max_prefixlen // 8
466 467 468 469 470
            details = ip_int.to_bytes(byteslen, 'big')
            msg = 'Netmask pattern %r mixes zeroes & ones'
            raise ValueError(msg % details)
        return prefixlen

471 472
    @classmethod
    def _report_invalid_netmask(cls, netmask_str):
473 474 475
        msg = '%r is not a valid netmask' % netmask_str
        raise NetmaskValueError(msg) from None

476 477
    @classmethod
    def _prefix_from_prefix_string(cls, prefixlen_str):
478 479 480 481
        """Return prefix length from a numeric string

        Args:
            prefixlen_str: The string to be converted
482 483 484 485

        Returns:
            An integer, the prefix length.

486 487
        Raises:
            NetmaskValueError: If the input is not a valid netmask
488
        """
489 490
        # int allows a leading +/- as well as surrounding whitespace,
        # so we ensure that isn't the case
491
        if not (prefixlen_str.isascii() and prefixlen_str.isdigit()):
492
            cls._report_invalid_netmask(prefixlen_str)
493 494 495
        try:
            prefixlen = int(prefixlen_str)
        except ValueError:
496 497 498
            cls._report_invalid_netmask(prefixlen_str)
        if not (0 <= prefixlen <= cls._max_prefixlen):
            cls._report_invalid_netmask(prefixlen_str)
499
        return prefixlen
500

501 502
    @classmethod
    def _prefix_from_ip_string(cls, ip_str):
503
        """Turn a netmask/hostmask string into a prefix length
504 505

        Args:
506
            ip_str: The netmask/hostmask to be converted
507 508

        Returns:
509
            An integer, the prefix length.
510

511 512
        Raises:
            NetmaskValueError: If the input is not a valid netmask/hostmask
513
        """
514 515
        # Parse the netmask/hostmask like an IP address.
        try:
516
            ip_int = cls._ip_int_from_string(ip_str)
517
        except AddressValueError:
518
            cls._report_invalid_netmask(ip_str)
519 520 521 522 523

        # Try matching a netmask (this would be /1*0*/ as a bitwise regexp).
        # Note that the two ambiguous cases (all-ones and all-zeroes) are
        # treated as netmasks.
        try:
524
            return cls._prefix_from_ip_int(ip_int)
525 526 527 528
        except ValueError:
            pass

        # Invert the bits, and try matching a /0+1+/ hostmask instead.
529
        ip_int ^= cls._ALL_ONES
530
        try:
531
            return cls._prefix_from_ip_int(ip_int)
532
        except ValueError:
533
            cls._report_invalid_netmask(ip_str)
534

535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558
    @classmethod
    def _split_addr_prefix(cls, address):
        """Helper function to parse address of Network/Interface.

        Arg:
            address: Argument of Network/Interface.

        Returns:
            (addr, prefix) tuple.
        """
        # a packed address or integer
        if isinstance(address, (bytes, int)):
            return address, cls._max_prefixlen

        if not isinstance(address, tuple):
            # Assume input argument to be string or any object representation
            # which converts into a formatted IP prefix string.
            address = _split_optional_netmask(address)

        # Constructing from a tuple (addr, [mask])
        if len(address) > 1:
            return address
        return address[0], cls._max_prefixlen

559 560 561
    def __reduce__(self):
        return self.__class__, (str(self),)

562

563
@functools.total_ordering
564 565 566 567 568 569 570 571
class _BaseAddress(_IPAddressBase):

    """A generic IP object.

    This IP class contains the version independent methods which are
    used by single IP addresses.
    """

572 573
    __slots__ = ()

574 575 576 577 578 579 580 581 582 583 584
    def __int__(self):
        return self._ip

    def __eq__(self, other):
        try:
            return (self._ip == other._ip
                    and self._version == other._version)
        except AttributeError:
            return NotImplemented

    def __lt__(self, other):
585 586
        if not isinstance(other, _BaseAddress):
            return NotImplemented
587 588
        if self._version != other._version:
            raise TypeError('%s and %s are not of the same version' % (
589
                             self, other))
590 591 592 593 594 595 596 597 598
        if self._ip != other._ip:
            return self._ip < other._ip
        return False

    # Shorthand for Integer addition and subtraction. This is not
    # meant to ever support addition/subtraction of addresses.
    def __add__(self, other):
        if not isinstance(other, int):
            return NotImplemented
599
        return self.__class__(int(self) + other)
600 601 602 603

    def __sub__(self, other):
        if not isinstance(other, int):
            return NotImplemented
604
        return self.__class__(int(self) - other)
605 606 607 608 609

    def __repr__(self):
        return '%s(%r)' % (self.__class__.__name__, str(self))

    def __str__(self):
610
        return str(self._string_from_ip_int(self._ip))
611 612 613 614 615 616 617

    def __hash__(self):
        return hash(hex(int(self._ip)))

    def _get_address_key(self):
        return (self._version, self)

618 619 620
    def __reduce__(self):
        return self.__class__, (self._ip,)

621

622
@functools.total_ordering
623
class _BaseNetwork(_IPAddressBase):
624
    """A generic IP network object.
625 626 627 628 629 630 631 632

    This IP class contains the version independent methods which are
    used by networks.
    """

    def __repr__(self):
        return '%s(%r)' % (self.__class__.__name__, str(self))

633
    def __str__(self):
634
        return '%s/%d' % (self.network_address, self.prefixlen)
635

636 637 638
    def hosts(self):
        """Generate Iterator over usable hosts in a network.

639 640
        This is like __iter__ except it doesn't return the network
        or broadcast addresses.
641 642

        """
643 644 645 646
        network = int(self.network_address)
        broadcast = int(self.broadcast_address)
        for x in range(network + 1, broadcast):
            yield self._address_class(x)
647 648

    def __iter__(self):
649 650 651 652
        network = int(self.network_address)
        broadcast = int(self.broadcast_address)
        for x in range(network, broadcast + 1):
            yield self._address_class(x)
653 654 655 656 657 658

    def __getitem__(self, n):
        network = int(self.network_address)
        broadcast = int(self.broadcast_address)
        if n >= 0:
            if network + n > broadcast:
659
                raise IndexError('address out of range')
660
            return self._address_class(network + n)
661 662 663
        else:
            n += 1
            if broadcast + n < network:
664
                raise IndexError('address out of range')
665
            return self._address_class(broadcast + n)
666 667

    def __lt__(self, other):
668 669
        if not isinstance(other, _BaseNetwork):
            return NotImplemented
670 671
        if self._version != other._version:
            raise TypeError('%s and %s are not of the same version' % (
672
                             self, other))
673 674 675 676 677 678 679
        if self.network_address != other.network_address:
            return self.network_address < other.network_address
        if self.netmask != other.netmask:
            return self.netmask < other.netmask
        return False

    def __eq__(self, other):
680 681 682 683 684 685
        try:
            return (self._version == other._version and
                    self.network_address == other.network_address and
                    int(self.netmask) == int(other.netmask))
        except AttributeError:
            return NotImplemented
686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709

    def __hash__(self):
        return hash(int(self.network_address) ^ int(self.netmask))

    def __contains__(self, other):
        # always false if one is v4 and the other is v6.
        if self._version != other._version:
            return False
        # dealing with another network.
        if isinstance(other, _BaseNetwork):
            return False
        # dealing with another address
        else:
            # address
            return (int(self.network_address) <= int(other._ip) <=
                    int(self.broadcast_address))

    def overlaps(self, other):
        """Tell if self is partly contained in other."""
        return self.network_address in other or (
            self.broadcast_address in other or (
                other.network_address in self or (
                    other.broadcast_address in self)))

710
    @functools.cached_property
711
    def broadcast_address(self):
712 713
        return self._address_class(int(self.network_address) |
                                   int(self.hostmask))
714

715
    @functools.cached_property
716
    def hostmask(self):
717
        return self._address_class(int(self.netmask) ^ self._ALL_ONES)
718 719 720

    @property
    def with_prefixlen(self):
721
        return '%s/%d' % (self.network_address, self._prefixlen)
722 723 724

    @property
    def with_netmask(self):
725
        return '%s/%s' % (self.network_address, self.netmask)
726 727 728

    @property
    def with_hostmask(self):
729
        return '%s/%s' % (self.network_address, self.hostmask)
730 731 732 733 734 735

    @property
    def num_addresses(self):
        """Number of hosts in the current subnet."""
        return int(self.broadcast_address) - int(self.network_address) + 1

736 737
    @property
    def _address_class(self):
738 739 740 741 742
        # Returning bare address objects (rather than interfaces) allows for
        # more consistent behaviour across the network address, broadcast
        # address and individual host addresses.
        msg = '%200s has no associated address class' % (type(self),)
        raise NotImplementedError(msg)
743

744 745 746 747 748 749 750 751 752 753 754
    @property
    def prefixlen(self):
        return self._prefixlen

    def address_exclude(self, other):
        """Remove an address from a larger block.

        For example:

            addr1 = ip_network('192.0.2.0/28')
            addr2 = ip_network('192.0.2.1/32')
755
            list(addr1.address_exclude(addr2)) =
756
                [IPv4Network('192.0.2.0/32'), IPv4Network('192.0.2.2/31'),
757
                 IPv4Network('192.0.2.4/30'), IPv4Network('192.0.2.8/29')]
758 759 760 761 762

        or IPv6:

            addr1 = ip_network('2001:db8::1/32')
            addr2 = ip_network('2001:db8::1/128')
763
            list(addr1.address_exclude(addr2)) =
764
                [ip_network('2001:db8::1/128'),
765 766 767 768 769
                 ip_network('2001:db8::2/127'),
                 ip_network('2001:db8::4/126'),
                 ip_network('2001:db8::8/125'),
                 ...
                 ip_network('2001:db8:8000::/33')]
770 771 772 773 774

        Args:
            other: An IPv4Network or IPv6Network object of the same type.

        Returns:
775
            An iterator of the IPv(4|6)Network objects which is self
776 777 778
            minus other.

        Raises:
779
            TypeError: If self and other are of differing address
780 781 782 783 784 785
              versions, or if other is not a network object.
            ValueError: If other is not completely contained by self.

        """
        if not self._version == other._version:
            raise TypeError("%s and %s are not of the same version" % (
786
                             self, other))
787 788

        if not isinstance(other, _BaseNetwork):
789
            raise TypeError("%s is not a network object" % other)
790

791
        if not other.subnet_of(self):
792
            raise ValueError('%s not contained in %s' % (other, self))
793
        if other == self:
794
            return
795 796

        # Make sure we're comparing the network of other.
797 798
        other = other.__class__('%s/%s' % (other.network_address,
                                           other.prefixlen))
799 800 801

        s1, s2 = self.subnets()
        while s1 != other and s2 != other:
802
            if other.subnet_of(s1):
803 804
                yield s2
                s1, s2 = s1.subnets()
805
            elif other.subnet_of(s2):
806 807 808 809 810 811
                yield s1
                s1, s2 = s2.subnets()
            else:
                # If we got here, there's a bug somewhere.
                raise AssertionError('Error performing exclusion: '
                                     's1: %s s2: %s other: %s' %
812
                                     (s1, s2, other))
813 814 815 816 817 818 819 820
        if s1 == other:
            yield s2
        elif s2 == other:
            yield s1
        else:
            # If we got here, there's a bug somewhere.
            raise AssertionError('Error performing exclusion: '
                                 's1: %s s2: %s other: %s' %
821
                                 (s1, s2, other))
822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857

    def compare_networks(self, other):
        """Compare two IP objects.

        This is only concerned about the comparison of the integer
        representation of the network addresses.  This means that the
        host bits aren't considered at all in this method.  If you want
        to compare host bits, you can easily enough do a
        'HostA._ip < HostB._ip'

        Args:
            other: An IP object.

        Returns:
            If the IP versions of self and other are the same, returns:

            -1 if self < other:
              eg: IPv4Network('192.0.2.0/25') < IPv4Network('192.0.2.128/25')
              IPv6Network('2001:db8::1000/124') <
                  IPv6Network('2001:db8::2000/124')
            0 if self == other
              eg: IPv4Network('192.0.2.0/24') == IPv4Network('192.0.2.0/24')
              IPv6Network('2001:db8::1000/124') ==
                  IPv6Network('2001:db8::1000/124')
            1 if self > other
              eg: IPv4Network('192.0.2.128/25') > IPv4Network('192.0.2.0/25')
                  IPv6Network('2001:db8::2000/124') >
                      IPv6Network('2001:db8::1000/124')

          Raises:
              TypeError if the IP versions are different.

        """
        # does this need to raise a ValueError?
        if self._version != other._version:
            raise TypeError('%s and %s are not of the same type' % (
858
                             self, other))
859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921
        # self._version == other._version below here:
        if self.network_address < other.network_address:
            return -1
        if self.network_address > other.network_address:
            return 1
        # self.network_address == other.network_address below here:
        if self.netmask < other.netmask:
            return -1
        if self.netmask > other.netmask:
            return 1
        return 0

    def _get_networks_key(self):
        """Network-only key function.

        Returns an object that identifies this address' network and
        netmask. This function is a suitable "key" argument for sorted()
        and list.sort().

        """
        return (self._version, self.network_address, self.netmask)

    def 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), yield an iterator 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

922
        if new_prefixlen > self._max_prefixlen:
923 924
            raise ValueError(
                'prefix length diff %d is invalid for netblock %s' % (
925
                    new_prefixlen, self))
926

927
        start = int(self.network_address)
928
        end = int(self.broadcast_address) + 1
929 930 931
        step = (int(self.hostmask) + 1) >> prefixlen_diff
        for new_addr in range(start, end, step):
            current = self.__class__((new_addr, new_prefixlen))
932 933 934 935 936 937 938 939 940 941 942 943 944 945 946
            yield current

    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:
947 948
            ValueError: If self.prefixlen - prefixlen_diff < 0. I.e., you have
              a negative prefix length.
949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964
                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

965 966
        new_prefixlen = self.prefixlen - prefixlen_diff
        if new_prefixlen < 0:
967 968 969
            raise ValueError(
                'current prefixlen is %d, cannot have a prefixlen_diff of %d' %
                (self.prefixlen, prefixlen_diff))
970 971 972 973
        return self.__class__((
            int(self.network_address) & (int(self.netmask) << prefixlen_diff),
            new_prefixlen
            ))
974

975 976 977 978 979 980 981 982 983 984 985 986
    @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.network_address.is_multicast and
                self.broadcast_address.is_multicast)

987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006
    @staticmethod
    def _is_subnet_of(a, b):
        try:
            # Always false if one is v4 and the other is v6.
            if a._version != b._version:
                raise TypeError(f"{a} and {b} are not of the same version")
            return (b.network_address <= a.network_address and
                    b.broadcast_address >= a.broadcast_address)
        except AttributeError:
            raise TypeError(f"Unable to test subnet containment "
                            f"between {a} and {b}")

    def subnet_of(self, other):
        """Return True if this network is a subnet of other."""
        return self._is_subnet_of(self, other)

    def supernet_of(self, other):
        """Return True if this network is a supernet of other."""
        return self._is_subnet_of(other, self)

1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034
    @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.

        """
        return (self.network_address.is_reserved and
                self.broadcast_address.is_reserved)

    @property
    def is_link_local(self):
        """Test if the address is reserved for link-local.

        Returns:
            A boolean, True if the address is reserved per RFC 4291.

        """
        return (self.network_address.is_link_local and
                self.broadcast_address.is_link_local)

    @property
    def is_private(self):
        """Test if this address is allocated for private networks.

        Returns:
1035 1036
            A boolean, True if the address is reserved per
            iana-ipv4-special-registry or iana-ipv6-special-registry.
1037 1038 1039 1040 1041

        """
        return (self.network_address.is_private and
                self.broadcast_address.is_private)

1042 1043
    @property
    def is_global(self):
1044
        """Test if this address is allocated for public networks.
1045 1046 1047 1048 1049 1050 1051 1052

        Returns:
            A boolean, True if the address is not reserved per
            iana-ipv4-special-registry or iana-ipv6-special-registry.

        """
        return not self.is_private

1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076
    @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 2373 2.5.2.

        """
        return (self.network_address.is_unspecified and
                self.broadcast_address.is_unspecified)

    @property
    def is_loopback(self):
        """Test if the address is a loopback address.

        Returns:
            A boolean, True if the address is a loopback address as defined in
            RFC 2373 2.5.3.

        """
        return (self.network_address.is_loopback and
                self.broadcast_address.is_loopback)

1077

1078
class _BaseV4:
1079 1080 1081 1082 1083 1084 1085 1086

    """Base IPv4 object.

    The following methods are used by IPv4 objects in both single IP
    addresses and networks.

    """

1087 1088
    __slots__ = ()
    _version = 4
1089 1090 1091
    # Equivalent to 255.255.255.255 or 32 bits of 1's.
    _ALL_ONES = (2**IPV4LENGTH) - 1

1092 1093 1094 1095 1096
    _max_prefixlen = IPV4LENGTH
    # There are only a handful of valid v4 netmasks, so we cache them all
    # when constructed (see _make_netmask()).
    _netmask_cache = {}

1097 1098 1099
    def _explode_shorthand_ip_string(self):
        return str(self)

1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125
    @classmethod
    def _make_netmask(cls, arg):
        """Make a (netmask, prefix_len) tuple from the given argument.

        Argument can be:
        - an integer (the prefix length)
        - a string representing the prefix length (e.g. "24")
        - a string representing the prefix netmask (e.g. "255.255.255.0")
        """
        if arg not in cls._netmask_cache:
            if isinstance(arg, int):
                prefixlen = arg
            else:
                try:
                    # Check for a netmask in prefix length form
                    prefixlen = cls._prefix_from_prefix_string(arg)
                except NetmaskValueError:
                    # Check for a netmask or hostmask in dotted-quad form.
                    # This may raise NetmaskValueError.
                    prefixlen = cls._prefix_from_ip_string(arg)
            netmask = IPv4Address(cls._ip_int_from_prefix(prefixlen))
            cls._netmask_cache[arg] = netmask, prefixlen
        return cls._netmask_cache[arg]

    @classmethod
    def _ip_int_from_string(cls, ip_str):
1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137
        """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.

        """
1138 1139 1140
        if not ip_str:
            raise AddressValueError('Address cannot be empty')

1141 1142
        octets = ip_str.split('.')
        if len(octets) != 4:
1143
            raise AddressValueError("Expected 4 octets in %r" % ip_str)
1144

1145
        try:
1146
            return int.from_bytes(map(cls._parse_octet, octets), 'big')
1147 1148
        except ValueError as exc:
            raise AddressValueError("%s in %r" % (exc, ip_str)) from None
1149

1150 1151
    @classmethod
    def _parse_octet(cls, octet_str):
1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163
        """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].

        """
1164 1165
        if not octet_str:
            raise ValueError("Empty octet not permitted")
1166
        # Whitelist the characters, since int() allows a lot of bizarre stuff.
1167
        if not (octet_str.isascii() and octet_str.isdigit()):
1168 1169 1170 1171 1172 1173 1174
            msg = "Only decimal digits permitted in %r"
            raise ValueError(msg % octet_str)
        # We do the length check second, since the invalid character error
        # is likely to be more informative for the user
        if len(octet_str) > 3:
            msg = "At most 3 characters permitted in %r"
            raise ValueError(msg % octet_str)
1175
        # Convert to integer (we know digits are legal)
1176
        octet_int = int(octet_str, 10)
1177
        if octet_int > 255:
1178
            raise ValueError("Octet %d (> 255) not permitted" % octet_int)
1179 1180
        return octet_int

1181 1182
    @classmethod
    def _string_from_ip_int(cls, ip_int):
1183 1184 1185 1186 1187 1188 1189 1190 1191
        """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.

        """
1192
        return '.'.join(map(str, ip_int.to_bytes(4, 'big')))
1193

1194 1195 1196 1197 1198 1199 1200 1201 1202
    def _reverse_pointer(self):
        """Return the reverse DNS pointer name for the IPv4 address.

        This implements the method described in RFC1035 3.5.

        """
        reverse_octets = str(self).split('.')[::-1]
        return '.'.join(reverse_octets) + '.in-addr.arpa'

1203 1204 1205 1206 1207 1208 1209 1210
    @property
    def max_prefixlen(self):
        return self._max_prefixlen

    @property
    def version(self):
        return self._version

1211 1212 1213 1214 1215

class IPv4Address(_BaseV4, _BaseAddress):

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

1216 1217
    __slots__ = ('_ip', '__weakref__')

1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242
    def __init__(self, address):

        """
        Args:
            address: A string or integer representing the IP

              Additionally, an integer can be passed, so
              IPv4Address('192.0.2.1') == IPv4Address(3221225985).
              or, more generally
              IPv4Address(int(IPv4Address('192.0.2.1'))) ==
                IPv4Address('192.0.2.1')

        Raises:
            AddressValueError: If ipaddress isn't a valid IPv4 address.

        """
        # Efficient constructor from integer.
        if isinstance(address, int):
            self._check_int_address(address)
            self._ip = address
            return

        # Constructing from a packed address
        if isinstance(address, bytes):
            self._check_packed_address(address, 4)
1243
            self._ip = int.from_bytes(address, 'big')
1244 1245 1246 1247 1248
            return

        # Assume input argument to be string or any object representation
        # which converts into a formatted IP string.
        addr_str = str(address)
1249 1250
        if '/' in addr_str:
            raise AddressValueError("Unexpected '/' in %r" % address)
1251 1252 1253 1254 1255 1256 1257
        self._ip = self._ip_int_from_string(addr_str)

    @property
    def packed(self):
        """The binary representation of this address."""
        return v4_int_to_packed(self._ip)

1258 1259 1260 1261 1262 1263 1264 1265 1266
    @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.

        """
1267
        return self in self._constants._reserved_network
1268 1269

    @property
1270
    @functools.lru_cache()
1271 1272 1273 1274
    def is_private(self):
        """Test if this address is allocated for private networks.

        Returns:
1275 1276
            A boolean, True if the address is reserved per
            iana-ipv4-special-registry.
1277 1278

        """
1279
        return any(self in net for net in self._constants._private_networks)
1280

1281 1282 1283 1284 1285
    @property
    @functools.lru_cache()
    def is_global(self):
        return self not in self._constants._public_network and not self.is_private

1286 1287 1288 1289 1290 1291 1292 1293 1294
    @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.

        """
1295
        return self in self._constants._multicast_network
1296 1297 1298 1299 1300 1301 1302 1303 1304 1305

    @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.

        """
1306
        return self == self._constants._unspecified_address
1307 1308 1309 1310 1311 1312 1313 1314 1315

    @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.

        """
1316
        return self in self._constants._loopback_network
1317 1318 1319 1320 1321 1322 1323 1324 1325

    @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.

        """
1326
        return self in self._constants._linklocal_network
1327 1328 1329 1330 1331


class IPv4Interface(IPv4Address):

    def __init__(self, address):
1332
        addr, mask = self._split_addr_prefix(address)
1333

1334 1335 1336
        IPv4Address.__init__(self, addr)
        self.network = IPv4Network((addr, mask), strict=False)
        self.netmask = self.network.netmask
1337 1338
        self._prefixlen = self.network._prefixlen

1339 1340 1341
    @functools.cached_property
    def hostmask(self):
        return self.network.hostmask
1342 1343 1344

    def __str__(self):
        return '%s/%d' % (self._string_from_ip_int(self._ip),
1345
                          self._prefixlen)
1346 1347

    def __eq__(self, other):
1348 1349 1350
        address_equal = IPv4Address.__eq__(self, other)
        if not address_equal or address_equal is NotImplemented:
            return address_equal
1351
        try:
1352
            return self.network == other.network
1353
        except AttributeError:
1354 1355 1356 1357 1358 1359 1360 1361
            # An interface with an associated network is NOT the
            # same as an unassociated address. That's why the hash
            # takes the extra info into account.
            return False

    def __lt__(self, other):
        address_less = IPv4Address.__lt__(self, other)
        if address_less is NotImplemented:
1362
            return NotImplemented
1363
        try:
1364 1365
            return (self.network < other.network or
                    self.network == other.network and address_less)
1366 1367 1368 1369
        except AttributeError:
            # We *do* allow addresses and interfaces to be sorted. The
            # unassociated address is considered less than all interfaces.
            return False
1370 1371 1372 1373

    def __hash__(self):
        return self._ip ^ self._prefixlen ^ int(self.network.network_address)

1374 1375
    __reduce__ = _IPAddressBase.__reduce__

1376 1377 1378 1379 1380 1381
    @property
    def ip(self):
        return IPv4Address(self._ip)

    @property
    def with_prefixlen(self):
1382 1383
        return '%s/%s' % (self._string_from_ip_int(self._ip),
                          self._prefixlen)
1384 1385 1386 1387 1388

    @property
    def with_netmask(self):
        return '%s/%s' % (self._string_from_ip_int(self._ip),
                          self.netmask)
1389

1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407
    @property
    def with_hostmask(self):
        return '%s/%s' % (self._string_from_ip_int(self._ip),
                          self.hostmask)


class IPv4Network(_BaseV4, _BaseNetwork):

    """This class represents and manipulates 32-bit IPv4 network + addresses..

    Attributes: [examples for IPv4Network('192.0.2.0/27')]
        .network_address: IPv4Address('192.0.2.0')
        .hostmask: IPv4Address('0.0.0.31')
        .broadcast_address: IPv4Address('192.0.2.32')
        .netmask: IPv4Address('255.255.255.224')
        .prefixlen: 27

    """
1408 1409
    # Class to use when creating address objects
    _address_class = IPv4Address
1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422

    def __init__(self, address, strict=True):
        """Instantiate a new IPv4 network object.

        Args:
            address: A string or integer representing the IP [& network].
              '192.0.2.0/24'
              '192.0.2.0/255.255.255.0'
              '192.0.0.2/0.0.0.255'
              are all functionally the same in IPv4. Similarly,
              '192.0.2.1'
              '192.0.2.1/255.255.255.255'
              '192.0.2.1/32'
1423
              are also functionally equivalent. That is to say, failing to
1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439
              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.0.2.1') == IPv4Network(3221225985)
              or, more generally
              IPv4Interface(int(IPv4Interface('192.0.2.1'))) ==
                IPv4Interface('192.0.2.1')

        Raises:
1440
            AddressValueError: If ipaddress isn't a valid IPv4 address.
1441 1442
            NetmaskValueError: If the netmask isn't valid for
              an IPv4 address.
1443
            ValueError: If strict is True and a network address is not
1444 1445
              supplied.
        """
1446
        addr, mask = self._split_addr_prefix(address)
1447 1448 1449 1450 1451 1452

        self.network_address = IPv4Address(addr)
        self.netmask, self._prefixlen = self._make_netmask(mask)
        packed = int(self.network_address)
        if packed & int(self.netmask) != packed:
            if strict:
1453
                raise ValueError('%s has host bits set' % self)
1454 1455 1456
            else:
                self.network_address = IPv4Address(packed &
                                                   int(self.netmask))
1457 1458 1459 1460

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

1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475
    @property
    @functools.lru_cache()
    def is_global(self):
        """Test if this address is allocated for public networks.

        Returns:
            A boolean, True if the address is not reserved per
            iana-ipv4-special-registry.

        """
        return (not (self.network_address in IPv4Network('100.64.0.0/10') and
                    self.broadcast_address in IPv4Network('100.64.0.0/10')) and
                not self.is_private)


1476 1477
class _IPv4Constants:
    _linklocal_network = IPv4Network('169.254.0.0/16')
1478

1479
    _loopback_network = IPv4Network('127.0.0.0/8')
1480

1481
    _multicast_network = IPv4Network('224.0.0.0/4')
1482

1483 1484
    _public_network = IPv4Network('100.64.0.0/10')

1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502
    _private_networks = [
        IPv4Network('0.0.0.0/8'),
        IPv4Network('10.0.0.0/8'),
        IPv4Network('127.0.0.0/8'),
        IPv4Network('169.254.0.0/16'),
        IPv4Network('172.16.0.0/12'),
        IPv4Network('192.0.0.0/29'),
        IPv4Network('192.0.0.170/31'),
        IPv4Network('192.0.2.0/24'),
        IPv4Network('192.168.0.0/16'),
        IPv4Network('198.18.0.0/15'),
        IPv4Network('198.51.100.0/24'),
        IPv4Network('203.0.113.0/24'),
        IPv4Network('240.0.0.0/4'),
        IPv4Network('255.255.255.255/32'),
        ]

    _reserved_network = IPv4Network('240.0.0.0/4')
1503

1504
    _unspecified_address = IPv4Address('0.0.0.0')
1505

1506 1507

IPv4Address._constants = _IPv4Constants
1508

1509

1510
class _BaseV6:
1511 1512 1513 1514 1515 1516 1517 1518

    """Base IPv6 object.

    The following methods are used by IPv6 objects in both single IP
    addresses and networks.

    """

1519 1520
    __slots__ = ()
    _version = 6
1521 1522 1523
    _ALL_ONES = (2**IPV6LENGTH) - 1
    _HEXTET_COUNT = 8
    _HEX_DIGITS = frozenset('0123456789ABCDEFabcdef')
1524 1525 1526 1527 1528
    _max_prefixlen = IPV6LENGTH

    # There are only a bunch of valid v6 netmasks, so we cache them all
    # when constructed (see _make_netmask()).
    _netmask_cache = {}
1529

1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549
    @classmethod
    def _make_netmask(cls, arg):
        """Make a (netmask, prefix_len) tuple from the given argument.

        Argument can be:
        - an integer (the prefix length)
        - a string representing the prefix length (e.g. "24")
        - a string representing the prefix netmask (e.g. "255.255.255.0")
        """
        if arg not in cls._netmask_cache:
            if isinstance(arg, int):
                prefixlen = arg
            else:
                prefixlen = cls._prefix_from_prefix_string(arg)
            netmask = IPv6Address(cls._ip_int_from_prefix(prefixlen))
            cls._netmask_cache[arg] = netmask, prefixlen
        return cls._netmask_cache[arg]

    @classmethod
    def _ip_int_from_string(cls, ip_str):
1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561
        """Turn an IPv6 ip_str into an integer.

        Args:
            ip_str: A string, the IPv6 ip_str.

        Returns:
            An int, the IPv6 address

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

        """
1562 1563 1564
        if not ip_str:
            raise AddressValueError('Address cannot be empty')

1565 1566 1567
        parts = ip_str.split(':')

        # An IPv6 address needs at least 2 colons (3 parts).
1568 1569 1570 1571
        _min_parts = 3
        if len(parts) < _min_parts:
            msg = "At least %d parts expected in %r" % (_min_parts, ip_str)
            raise AddressValueError(msg)
1572 1573 1574

        # If the address has an IPv4-style suffix, convert it to hexadecimal.
        if '.' in parts[-1]:
1575 1576 1577 1578
            try:
                ipv4_int = IPv4Address(parts.pop())._ip
            except AddressValueError as exc:
                raise AddressValueError("%s in %r" % (exc, ip_str)) from None
1579 1580 1581 1582
            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).
1583 1584
        # The extra colon comes from using the "::" notation for a single
        # leading or trailing zero part.
1585
        _max_parts = cls._HEXTET_COUNT + 1
1586 1587 1588
        if len(parts) > _max_parts:
            msg = "At most %d colons permitted in %r" % (_max_parts-1, ip_str)
            raise AddressValueError(msg)
1589 1590 1591

        # Disregarding the endpoints, find '::' with nothing in between.
        # This indicates that a run of zeroes has been skipped.
1592 1593 1594 1595 1596 1597 1598 1599
        skip_index = None
        for i in range(1, len(parts) - 1):
            if not parts[i]:
                if skip_index is not None:
                    # Can't have more than one '::'
                    msg = "At most one '::' permitted in %r" % ip_str
                    raise AddressValueError(msg)
                skip_index = i
1600 1601 1602 1603 1604 1605 1606 1607 1608 1609

        # 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:
1610 1611
                    msg = "Leading ':' only permitted as part of '::' in %r"
                    raise AddressValueError(msg % ip_str)  # ^: requires ^::
1612 1613 1614
            if not parts[-1]:
                parts_lo -= 1
                if parts_lo:
1615 1616
                    msg = "Trailing ':' only permitted as part of '::' in %r"
                    raise AddressValueError(msg % ip_str)  # :$ requires ::$
1617
            parts_skipped = cls._HEXTET_COUNT - (parts_hi + parts_lo)
1618
            if parts_skipped < 1:
1619
                msg = "Expected at most %d other parts with '::' in %r"
1620
                raise AddressValueError(msg % (cls._HEXTET_COUNT-1, ip_str))
1621
        else:
1622 1623 1624
            # Otherwise, allocate the entire address to parts_hi.  The
            # endpoints could still be empty, but _parse_hextet() will check
            # for that.
1625
            if len(parts) != cls._HEXTET_COUNT:
1626
                msg = "Exactly %d parts expected without '::' in %r"
1627
                raise AddressValueError(msg % (cls._HEXTET_COUNT, ip_str))
1628 1629 1630 1631 1632 1633
            if not parts[0]:
                msg = "Leading ':' only permitted as part of '::' in %r"
                raise AddressValueError(msg % ip_str)  # ^: requires ^::
            if not parts[-1]:
                msg = "Trailing ':' only permitted as part of '::' in %r"
                raise AddressValueError(msg % ip_str)  # :$ requires ::$
1634 1635 1636 1637 1638 1639 1640 1641 1642
            parts_hi = len(parts)
            parts_lo = 0
            parts_skipped = 0

        try:
            # Now, parse the hextets into a 128-bit integer.
            ip_int = 0
            for i in range(parts_hi):
                ip_int <<= 16
1643
                ip_int |= cls._parse_hextet(parts[i])
1644 1645 1646
            ip_int <<= 16 * parts_skipped
            for i in range(-parts_lo, 0):
                ip_int <<= 16
1647
                ip_int |= cls._parse_hextet(parts[i])
1648
            return ip_int
1649 1650
        except ValueError as exc:
            raise AddressValueError("%s in %r" % (exc, ip_str)) from None
1651

1652 1653
    @classmethod
    def _parse_hextet(cls, hextet_str):
1654 1655 1656 1657 1658 1659 1660 1661 1662
        """Convert an IPv6 hextet string into an integer.

        Args:
            hextet_str: A string, the number to parse.

        Returns:
            The hextet as an integer.

        Raises:
1663 1664
            ValueError: if the input isn't strictly a hex number from
              [0..FFFF].
1665 1666 1667

        """
        # Whitelist the characters, since int() allows a lot of bizarre stuff.
1668
        if not cls._HEX_DIGITS.issuperset(hextet_str):
1669
            raise ValueError("Only hex digits permitted in %r" % hextet_str)
1670 1671
        # We do the length check second, since the invalid character error
        # is likely to be more informative for the user
1672
        if len(hextet_str) > 4:
1673 1674
            msg = "At most 4 characters permitted in %r"
            raise ValueError(msg % hextet_str)
1675 1676
        # Length check means we can skip checking the integer value
        return int(hextet_str, 16)
1677

1678 1679
    @classmethod
    def _compress_hextets(cls, hextets):
1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698
        """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
1699 1700
        for index, hextet in enumerate(hextets):
            if hextet == '0':
1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725
                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

1726 1727
    @classmethod
    def _string_from_ip_int(cls, ip_int=None):
1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739
        """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.

        """
1740
        if ip_int is None:
1741
            ip_int = int(cls._ip)
1742

1743
        if ip_int > cls._ALL_ONES:
1744 1745 1746
            raise ValueError('IPv6 address is too large')

        hex_str = '%032x' % ip_int
1747
        hextets = ['%x' % int(hex_str[x:x+4], 16) for x in range(0, 32, 4)]
1748

1749
        hextets = cls._compress_hextets(hextets)
1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769
        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, IPv6Network):
            ip_str = str(self.network_address)
        elif isinstance(self, IPv6Interface):
            ip_str = str(self.ip)
        else:
            ip_str = str(self)

        ip_int = self._ip_int_from_string(ip_str)
1770 1771
        hex_str = '%032x' % ip_int
        parts = [hex_str[x:x+4] for x in range(0, 32, 4)]
1772
        if isinstance(self, (_BaseNetwork, IPv6Interface)):
1773
            return '%s/%d' % (':'.join(parts), self._prefixlen)
1774 1775
        return ':'.join(parts)

1776 1777 1778 1779 1780 1781 1782 1783 1784
    def _reverse_pointer(self):
        """Return the reverse DNS pointer name for the IPv6 address.

        This implements the method described in RFC3596 2.5.

        """
        reverse_chars = self.exploded[::-1].replace(':', '')
        return '.'.join(reverse_chars) + '.ip6.arpa'

1785 1786 1787 1788 1789 1790 1791 1792
    @property
    def max_prefixlen(self):
        return self._max_prefixlen

    @property
    def version(self):
        return self._version

1793 1794 1795 1796 1797

class IPv6Address(_BaseV6, _BaseAddress):

    """Represent and manipulate single IPv6 Addresses."""

1798 1799
    __slots__ = ('_ip', '__weakref__')

1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825
    def __init__(self, address):
        """Instantiate a new IPv6 address object.

        Args:
            address: A string or integer representing the IP

              Additionally, an integer can be passed, so
              IPv6Address('2001:db8::') ==
                IPv6Address(42540766411282592856903984951653826560)
              or, more generally
              IPv6Address(int(IPv6Address('2001:db8::'))) ==
                IPv6Address('2001:db8::')

        Raises:
            AddressValueError: If address isn't a valid IPv6 address.

        """
        # Efficient constructor from integer.
        if isinstance(address, int):
            self._check_int_address(address)
            self._ip = address
            return

        # Constructing from a packed address
        if isinstance(address, bytes):
            self._check_packed_address(address, 16)
1826
            self._ip = int.from_bytes(address, 'big')
1827 1828 1829 1830 1831
            return

        # Assume input argument to be string or any object representation
        # which converts into a formatted IP string.
        addr_str = str(address)
1832 1833
        if '/' in addr_str:
            raise AddressValueError("Unexpected '/' in %r" % address)
1834 1835 1836 1837 1838 1839 1840
        self._ip = self._ip_int_from_string(addr_str)

    @property
    def packed(self):
        """The binary representation of this address."""
        return v6_int_to_packed(self._ip)

1841 1842 1843 1844 1845 1846 1847 1848 1849
    @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.

        """
1850
        return self in self._constants._multicast_network
1851 1852 1853 1854 1855 1856 1857 1858 1859 1860

    @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.

        """
1861
        return any(self in x for x in self._constants._reserved_networks)
1862 1863 1864 1865 1866 1867 1868 1869 1870

    @property
    def is_link_local(self):
        """Test if the address is reserved for link-local.

        Returns:
            A boolean, True if the address is reserved per RFC 4291.

        """
1871
        return self in self._constants._linklocal_network
1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884

    @property
    def is_site_local(self):
        """Test if the address is reserved for site-local.

        Note that the site-local address space has been deprecated by RFC 3879.
        Use is_private to test if this address is in the space of unique local
        addresses as defined by RFC 4193.

        Returns:
            A boolean, True if the address is reserved per RFC 3513 2.5.6.

        """
1885
        return self in self._constants._sitelocal_network
1886 1887

    @property
1888
    @functools.lru_cache()
1889 1890 1891 1892
    def is_private(self):
        """Test if this address is allocated for private networks.

        Returns:
1893 1894 1895 1896
            A boolean, True if the address is reserved per
            iana-ipv6-special-registry.

        """
1897
        return any(self in net for net in self._constants._private_networks)
1898 1899 1900 1901 1902 1903 1904 1905

    @property
    def is_global(self):
        """Test if this address is allocated for public networks.

        Returns:
            A boolean, true if the address is not reserved per
            iana-ipv6-special-registry.
1906 1907

        """
1908
        return not self.is_private
1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930

    @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 2373 2.5.2.

        """
        return self._ip == 0

    @property
    def is_loopback(self):
        """Test if the address is a loopback address.

        Returns:
            A boolean, True if the address is a loopback address as defined in
            RFC 2373 2.5.3.

        """
        return self._ip == 1
1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976

    @property
    def ipv4_mapped(self):
        """Return the IPv4 mapped address.

        Returns:
            If the IPv6 address is a v4 mapped address, return the
            IPv4 mapped address. Return None otherwise.

        """
        if (self._ip >> 32) != 0xFFFF:
            return None
        return IPv4Address(self._ip & 0xFFFFFFFF)

    @property
    def teredo(self):
        """Tuple of embedded teredo IPs.

        Returns:
            Tuple of the (server, client) IPs or None if the address
            doesn't appear to be a teredo address (doesn't start with
            2001::/32)

        """
        if (self._ip >> 96) != 0x20010000:
            return None
        return (IPv4Address((self._ip >> 64) & 0xFFFFFFFF),
                IPv4Address(~self._ip & 0xFFFFFFFF))

    @property
    def sixtofour(self):
        """Return the IPv4 6to4 embedded address.

        Returns:
            The IPv4 6to4-embedded address if present or None if the
            address doesn't appear to contain a 6to4 embedded address.

        """
        if (self._ip >> 112) != 0x2002:
            return None
        return IPv4Address((self._ip >> 80) & 0xFFFFFFFF)


class IPv6Interface(IPv6Address):

    def __init__(self, address):
1977
        addr, mask = self._split_addr_prefix(address)
1978

1979 1980
        IPv6Address.__init__(self, addr)
        self.network = IPv6Network((addr, mask), strict=False)
1981 1982
        self.netmask = self.network.netmask
        self._prefixlen = self.network._prefixlen
1983 1984 1985 1986

    @functools.cached_property
    def hostmask(self):
        return self.network.hostmask
1987 1988 1989

    def __str__(self):
        return '%s/%d' % (self._string_from_ip_int(self._ip),
1990
                          self._prefixlen)
1991 1992

    def __eq__(self, other):
1993 1994 1995
        address_equal = IPv6Address.__eq__(self, other)
        if not address_equal or address_equal is NotImplemented:
            return address_equal
1996
        try:
1997
            return self.network == other.network
1998
        except AttributeError:
1999 2000 2001 2002 2003 2004 2005 2006
            # An interface with an associated network is NOT the
            # same as an unassociated address. That's why the hash
            # takes the extra info into account.
            return False

    def __lt__(self, other):
        address_less = IPv6Address.__lt__(self, other)
        if address_less is NotImplemented:
2007
            return NotImplemented
2008
        try:
2009 2010
            return (self.network < other.network or
                    self.network == other.network and address_less)
2011 2012 2013 2014
        except AttributeError:
            # We *do* allow addresses and interfaces to be sorted. The
            # unassociated address is considered less than all interfaces.
            return False
2015 2016 2017 2018

    def __hash__(self):
        return self._ip ^ self._prefixlen ^ int(self.network.network_address)

2019 2020
    __reduce__ = _IPAddressBase.__reduce__

2021 2022 2023 2024 2025 2026
    @property
    def ip(self):
        return IPv6Address(self._ip)

    @property
    def with_prefixlen(self):
2027 2028
        return '%s/%s' % (self._string_from_ip_int(self._ip),
                          self._prefixlen)
2029 2030 2031

    @property
    def with_netmask(self):
2032 2033
        return '%s/%s' % (self._string_from_ip_int(self._ip),
                          self.netmask)
2034

2035 2036 2037 2038 2039
    @property
    def with_hostmask(self):
        return '%s/%s' % (self._string_from_ip_int(self._ip),
                          self.hostmask)

2040 2041 2042 2043 2044 2045 2046 2047
    @property
    def is_unspecified(self):
        return self._ip == 0 and self.network.is_unspecified

    @property
    def is_loopback(self):
        return self._ip == 1 and self.network.is_loopback

2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061

class IPv6Network(_BaseV6, _BaseNetwork):

    """This class represents and manipulates 128-bit IPv6 networks.

    Attributes: [examples for IPv6('2001:db8::1000/124')]
        .network_address: IPv6Address('2001:db8::1000')
        .hostmask: IPv6Address('::f')
        .broadcast_address: IPv6Address('2001:db8::100f')
        .netmask: IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff:ffff:fff0')
        .prefixlen: 124

    """

2062 2063 2064
    # Class to use when creating address objects
    _address_class = IPv6Address

2065 2066 2067 2068
    def __init__(self, address, strict=True):
        """Instantiate a new IPv6 Network object.

        Args:
2069 2070
            address: A string or integer representing the IPv6 network or the
              IP and prefix/netmask.
2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095
              '2001:db8::/128'
              '2001:db8:0000:0000:0000:0000:0000:0000/128'
              '2001:db8::'
              are all functionally the same in IPv6.  That is to say,
              failing to provide a subnetmask will create an object with
              a mask of /128.

              Additionally, an integer can be passed, so
              IPv6Network('2001:db8::') ==
                IPv6Network(42540766411282592856903984951653826560)
              or, more generally
              IPv6Network(int(IPv6Network('2001:db8::'))) ==
                IPv6Network('2001:db8::')

            strict: A boolean. If true, ensure that we have been passed
              A true network address, eg, 2001:db8::1000/124 and not an
              IP address on a network, eg, 2001:db8::1/124.

        Raises:
            AddressValueError: If address isn't a valid IPv6 address.
            NetmaskValueError: If the netmask isn't valid for
              an IPv6 address.
            ValueError: If strict was True and a network address was not
              supplied.
        """
2096
        addr, mask = self._split_addr_prefix(address)
2097 2098 2099 2100 2101 2102

        self.network_address = IPv6Address(addr)
        self.netmask, self._prefixlen = self._make_netmask(mask)
        packed = int(self.network_address)
        if packed & int(self.netmask) != packed:
            if strict:
2103
                raise ValueError('%s has host bits set' % self)
2104 2105 2106
            else:
                self.network_address = IPv6Address(packed &
                                                   int(self.netmask))
2107 2108 2109 2110

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

2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122
    def hosts(self):
        """Generate Iterator over usable hosts in a network.

          This is like __iter__ except it doesn't return the
          Subnet-Router anycast address.

        """
        network = int(self.network_address)
        broadcast = int(self.broadcast_address)
        for x in range(network + 1, broadcast + 1):
            yield self._address_class(x)

2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136
    @property
    def is_site_local(self):
        """Test if the address is reserved for site-local.

        Note that the site-local address space has been deprecated by RFC 3879.
        Use is_private to test if this address is in the space of unique local
        addresses as defined by RFC 4193.

        Returns:
            A boolean, True if the address is reserved per RFC 3513 2.5.6.

        """
        return (self.network_address.is_site_local and
                self.broadcast_address.is_site_local)
2137 2138


2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166
class _IPv6Constants:

    _linklocal_network = IPv6Network('fe80::/10')

    _multicast_network = IPv6Network('ff00::/8')

    _private_networks = [
        IPv6Network('::1/128'),
        IPv6Network('::/128'),
        IPv6Network('::ffff:0:0/96'),
        IPv6Network('100::/64'),
        IPv6Network('2001::/23'),
        IPv6Network('2001:2::/48'),
        IPv6Network('2001:db8::/32'),
        IPv6Network('2001:10::/28'),
        IPv6Network('fc00::/7'),
        IPv6Network('fe80::/10'),
        ]

    _reserved_networks = [
        IPv6Network('::/8'), IPv6Network('100::/8'),
        IPv6Network('200::/7'), IPv6Network('400::/6'),
        IPv6Network('800::/5'), IPv6Network('1000::/4'),
        IPv6Network('4000::/3'), IPv6Network('6000::/3'),
        IPv6Network('8000::/3'), IPv6Network('A000::/3'),
        IPv6Network('C000::/3'), IPv6Network('E000::/4'),
        IPv6Network('F000::/5'), IPv6Network('F800::/6'),
        IPv6Network('FE00::/9'),
2167 2168
    ]

2169 2170
    _sitelocal_network = IPv6Network('fec0::/10')

2171

2172
IPv6Address._constants = _IPv6Constants