csit/libraries/BGPCEP/ipaddr.py

   1 #!/usr/bin/python
   2 #
   3 # Copyright 2007 Google Inc.
   4 #  Licensed to PSF under a Contributor Agreement.
   5 #
   6 # Licensed under the Apache License, Version 2.0 (the "License");
   7 # you may not use this file except in compliance with the License.
   8 # You may obtain a copy of the License at
   9 #
  10 #      http://www.apache.org/licenses/LICENSE-2.0
  11 #
  12 # Unless required by applicable law or agreed to in writing, software
  13 # distributed under the License is distributed on an "AS IS" BASIS,
  14 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  15 # implied. See the License for the specific language governing
  16 # permissions and limitations under the License.
  17
  18 """A fast, lightweight IPv4/IPv6 manipulation library in Python.
  19
  20 This library is used to create/poke/manipulate IPv4 and IPv6 addresses
  21 and networks.
  22
  23 """
  24
  25 import struct
  26
  27
  28 __version__ = "2.1.11"
  29
  30
  31 IPV4LENGTH = 32
  32 IPV6LENGTH = 128
  33
  34
  35 class AddressValueError(ValueError):
  36     """A Value Error related to the address."""
  37
  38
  39 class NetmaskValueError(ValueError):
  40     """A Value Error related to the netmask."""
  41
  42
  43 def IPAddress(address, version=None):
  44     """Take an IP string/int and return an object of the correct type.
  45
  46     Args:
  47         address: A string or integer, the IP address.  Either IPv4 or
  48           IPv6 addresses may be supplied; integers less than 2**32 will
  49           be considered to be IPv4 by default.
  50         version: An Integer, 4 or 6. If set, don't try to automatically
  51           determine what the IP address type is. important for things
  52           like IPAddress(1), which could be IPv4, '0.0.0.1',  or IPv6,
  53           '::1'.
  54
  55     Returns:
  56         An IPv4Address or IPv6Address object.
  57
  58     Raises:
  59         ValueError: if the string passed isn't either a v4 or a v6
  60           address.
  61
  62     """
  63     if version:
  64         if version == 4:
  65             return IPv4Address(address)
  66         elif version == 6:
  67             return IPv6Address(address)
  68
  69     try:
  70         return IPv4Address(address)
  71     except (AddressValueError, NetmaskValueError):
  72         pass
  73
  74     try:
  75         return IPv6Address(address)
  76     except (AddressValueError, NetmaskValueError):
  77         pass
  78
  79     raise ValueError("%r does not appear to be an IPv4 or IPv6 address" % address)
  80
  81
  82 def IPNetwork(address, version=None, strict=False):
  83     """Take an IP string/int and return an object of the correct type.
  84
  85     Args:
  86         address: A string or integer, the IP address.  Either IPv4 or
  87           IPv6 addresses may be supplied; integers less than 2**32 will
  88           be considered to be IPv4 by default.
  89         version: An Integer, if set, don't try to automatically
  90           determine what the IP address type is. important for things
  91           like IPNetwork(1), which could be IPv4, '0.0.0.1/32', or IPv6,
  92           '::1/128'.
  93
  94     Returns:
  95         An IPv4Network or IPv6Network object.
  96
  97     Raises:
  98         ValueError: if the string passed isn't either a v4 or a v6
  99           address. Or if a strict network was requested and a strict
 100           network wasn't given.
 101
 102     """
 103     if version:
 104         if version == 4:
 105             return IPv4Network(address, strict)
 106         elif version == 6:
 107             return IPv6Network(address, strict)
 108
 109     try:
 110         return IPv4Network(address, strict)
 111     except (AddressValueError, NetmaskValueError):
 112         pass
 113
 114     try:
 115         return IPv6Network(address, strict)
 116     except (AddressValueError, NetmaskValueError):
 117         pass
 118
 119     raise ValueError("%r does not appear to be an IPv4 or IPv6 network" % address)
 120
 121
 122 def v4_int_to_packed(address):
 123     """The binary representation of this address.
 124
 125     Args:
 126         address: An integer representation of an IPv4 IP address.
 127
 128     Returns:
 129         The binary representation of this address.
 130
 131     Raises:
 132         ValueError: If the integer is too large to be an IPv4 IP
 133           address.
 134     """
 135     if address > _BaseV4._ALL_ONES:
 136         raise ValueError("Address too large for IPv4")
 137     return Bytes(struct.pack("!I", address))
 138
 139
 140 def v6_int_to_packed(address):
 141     """The binary representation of this address.
 142
 143     Args:
 144         address: An integer representation of an IPv6 IP address.
 145
 146     Returns:
 147         The binary representation of this address.
 148     """
 149     return Bytes(struct.pack("!QQ", address >> 64, address & (2**64 - 1)))
 150
 151
 152 def _find_address_range(addresses):
 153     """Find a sequence of addresses.
 154
 155     Args:
 156         addresses: a list of IPv4 or IPv6 addresses.
 157
 158     Returns:
 159         A tuple containing the first and last IP addresses in the sequence.
 160
 161     """
 162     first = last = addresses[0]
 163     for ip in addresses[1:]:
 164         if ip._ip == last._ip + 1:
 165             last = ip
 166         else:
 167             break
 168     return (first, last)
 169
 170
 171 def _get_prefix_length(number1, number2, bits):
 172     """Get the number of leading bits that are same for two numbers.
 173
 174     Args:
 175         number1: an integer.
 176         number2: another integer.
 177         bits: the maximum number of bits to compare.
 178
 179     Returns:
 180         The number of leading bits that are the same for two numbers.
 181
 182     """
 183     for i in range(bits):
 184         if number1 >> i == number2 >> i:
 185             return bits - i
 186     return 0
 187
 188
 189 def _count_righthand_zero_bits(number, bits):
 190     """Count the number of zero bits on the right hand side.
 191
 192     Args:
 193         number: an integer.
 194         bits: maximum number of bits to count.
 195
 196     Returns:
 197         The number of zero bits on the right hand side of the number.
 198
 199     """
 200     if number == 0:
 201         return bits
 202     for i in range(bits):
 203         if (number >> i) % 2:
 204             return i
 205
 206
 207 def summarize_address_range(first, last):
 208     """Summarize a network range given the first and last IP addresses.
 209
 210     Example:
 211         >>> summarize_address_range(IPv4Address('1.1.1.0'),
 212             IPv4Address('1.1.1.130'))
 213         [IPv4Network('1.1.1.0/25'), IPv4Network('1.1.1.128/31'),
 214         IPv4Network('1.1.1.130/32')]
 215
 216     Args:
 217         first: the first IPv4Address or IPv6Address in the range.
 218         last: the last IPv4Address or IPv6Address in the range.
 219
 220     Returns:
 221         The address range collapsed to a list of IPv4Network's or
 222         IPv6Network's.
 223
 224     Raise:
 225         TypeError:
 226             If the first and last objects are not IP addresses.
 227             If the first and last objects are not the same version.
 228         ValueError:
 229             If the last object is not greater than the first.
 230             If the version is not 4 or 6.
 231
 232     """
 233     if not (isinstance(first, _BaseIP) and isinstance(last, _BaseIP)):
 234         raise TypeError("first and last must be IP addresses, not networks")
 235     if first.version != last.version:
 236         raise TypeError(
 237             "%s and %s are not of the same version" % (str(first), str(last))
 238         )
 239     if first > last:
 240         raise ValueError("last IP address must be greater than first")
 241
 242     networks = []
 243
 244     if first.version == 4:
 245         ip = IPv4Network
 246     elif first.version == 6:
 247         ip = IPv6Network
 248     else:
 249         raise ValueError("unknown IP version")
 250
 251     ip_bits = first._max_prefixlen
 252     first_int = first._ip
 253     last_int = last._ip
 254     while first_int <= last_int:
 255         nbits = _count_righthand_zero_bits(first_int, ip_bits)
 256         current = None
 257         while nbits >= 0:
 258             addend = 2**nbits - 1
 259             current = first_int + addend
 260             nbits -= 1
 261             if current <= last_int:
 262                 break
 263         prefix = _get_prefix_length(first_int, current, ip_bits)
 264         net = ip("%s/%d" % (str(first), prefix))
 265         networks.append(net)
 266         if current == ip._ALL_ONES:
 267             break
 268         first_int = current + 1
 269         first = IPAddress(first_int, version=first._version)
 270     return networks
 271
 272
 273 def _collapse_address_list_recursive(addresses):
 274     """Loops through the addresses, collapsing concurrent netblocks.
 275
 276     Example:
 277
 278         ip1 = IPv4Network('1.1.0.0/24')
 279         ip2 = IPv4Network('1.1.1.0/24')
 280         ip3 = IPv4Network('1.1.2.0/24')
 281         ip4 = IPv4Network('1.1.3.0/24')
 282         ip5 = IPv4Network('1.1.4.0/24')
 283         ip6 = IPv4Network('1.1.0.1/22')
 284
 285         _collapse_address_list_recursive([ip1, ip2, ip3, ip4, ip5, ip6]) ->
 286           [IPv4Network('1.1.0.0/22'), IPv4Network('1.1.4.0/24')]
 287
 288         This shouldn't be called directly; it is called via
 289           collapse_address_list([]).
 290
 291     Args:
 292         addresses: A list of IPv4Network's or IPv6Network's
 293
 294     Returns:
 295         A list of IPv4Network's or IPv6Network's depending on what we were
 296         passed.
 297
 298     """
 299     ret_array = []
 300     optimized = False
 301
 302     for cur_addr in addresses:
 303         if not ret_array:
 304             ret_array.append(cur_addr)
 305             continue
 306         if cur_addr in ret_array[-1]:
 307             optimized = True
 308         elif cur_addr == ret_array[-1].supernet().subnet()[1]:
 309             ret_array.append(ret_array.pop().supernet())
 310             optimized = True
 311         else:
 312             ret_array.append(cur_addr)
 313
 314     if optimized:
 315         return _collapse_address_list_recursive(ret_array)
 316
 317     return ret_array
 318
 319
 320 def collapse_address_list(addresses):
 321     """Collapse a list of IP objects.
 322
 323     Example:
 324         collapse_address_list([IPv4('1.1.0.0/24'), IPv4('1.1.1.0/24')]) ->
 325           [IPv4('1.1.0.0/23')]
 326
 327     Args:
 328         addresses: A list of IPv4Network or IPv6Network objects.
 329
 330     Returns:
 331         A list of IPv4Network or IPv6Network objects depending on what we
 332         were passed.
 333
 334     Raises:
 335         TypeError: If passed a list of mixed version objects.
 336
 337     """
 338     i = 0
 339     addrs = []
 340     ips = []
 341     nets = []
 342
 343     # split IP addresses and networks
 344     for ip in addresses:
 345         if isinstance(ip, _BaseIP):
 346             if ips and ips[-1]._version != ip._version:
 347                 raise TypeError(
 348                     "%s and %s are not of the same version" % (str(ip), str(ips[-1]))
 349                 )
 350             ips.append(ip)
 351         elif ip._prefixlen == ip._max_prefixlen:
 352             if ips and ips[-1]._version != ip._version:
 353                 raise TypeError(
 354                     "%s and %s are not of the same version" % (str(ip), str(ips[-1]))
 355                 )
 356             ips.append(ip.ip)
 357         else:
 358             if nets and nets[-1]._version != ip._version:
 359                 raise TypeError(
 360                     "%s and %s are not of the same version" % (str(ip), str(nets[-1]))
 361                 )
 362             nets.append(ip)
 363
 364     # sort and dedup
 365     ips = sorted(set(ips))
 366     nets = sorted(set(nets))
 367
 368     while i < len(ips):
 369         (first, last) = _find_address_range(ips[i:])
 370         i = ips.index(last) + 1
 371         addrs.extend(summarize_address_range(first, last))
 372
 373     return _collapse_address_list_recursive(
 374         sorted(addrs + nets, key=_BaseNet._get_networks_key)
 375     )
 376
 377
 378 # backwards compatibility
 379 CollapseAddrList = collapse_address_list
 380
 381 # We need to distinguish between the string and packed-bytes representations
 382 # of an IP address.  For example, b'0::1' is the IPv4 address 48.58.58.49,
 383 # while '0::1' is an IPv6 address.
 384 #
 385 # In Python 3, the native 'bytes' type already provides this functionality,
 386 # so we use it directly.  For earlier implementations where bytes is not a
 387 # distinct type, we create a subclass of str to serve as a tag.
 388 #
 389 # Usage example (Python 2):
 390 #   ip = ipaddr.IPAddress(ipaddr.Bytes('xxxx'))
 391 #
 392 # Usage example (Python 3):
 393 #   ip = ipaddr.IPAddress(b'xxxx')
 394 try:
 395     if bytes is str:
 396         raise TypeError("bytes is not a distinct type")
 397     Bytes = bytes
 398 except (NameError, TypeError):
 399
 400     class Bytes(str):
 401         def __repr__(self):
 402             return "Bytes(%s)" % str.__repr__(self)
 403
 404
 405 def get_mixed_type_key(obj):
 406     """Return a key suitable for sorting between networks and addresses.
 407
 408     Address and Network objects are not sortable by default; they're
 409     fundamentally different so the expression
 410
 411         IPv4Address('1.1.1.1') <= IPv4Network('1.1.1.1/24')
 412
 413     doesn't make any sense.  There are some times however, where you may wish
 414     to have ipaddr sort these for you anyway. If you need to do this, you
 415     can use this function as the key= argument to sorted().
 416
 417     Args:
 418       obj: either a Network or Address object.
 419     Returns:
 420       appropriate key.
 421
 422     """
 423     if isinstance(obj, _BaseNet):
 424         return obj._get_networks_key()
 425     elif isinstance(obj, _BaseIP):
 426         return obj._get_address_key()
 427     return NotImplemented
 428
 429
 430 class _IPAddrBase(object):
 431
 432     """The mother class."""
 433
 434     def __index__(self):
 435         return self._ip
 436
 437     def __int__(self):
 438         return self._ip
 439
 440     def __hex__(self):
 441         return hex(self._ip)
 442
 443     @property
 444     def exploded(self):
 445         """Return the longhand version of the IP address as a string."""
 446         return self._explode_shorthand_ip_string()
 447
 448     @property
 449     def compressed(self):
 450         """Return the shorthand version of the IP address as a string."""
 451         return str(self)
 452
 453
 454 class _BaseIP(_IPAddrBase):
 455
 456     """A generic IP object.
 457
 458     This IP class contains the version independent methods which are
 459     used by single IP addresses.
 460
 461     """
 462
 463     def __eq__(self, other):
 464         try:
 465             return self._ip == other._ip and self._version == other._version
 466         except AttributeError:
 467             return NotImplemented
 468
 469     def __ne__(self, other):
 470         eq = self.__eq__(other)
 471         if eq is NotImplemented:
 472             return NotImplemented
 473         return not eq
 474
 475     def __le__(self, other):
 476         gt = self.__gt__(other)
 477         if gt is NotImplemented:
 478             return NotImplemented
 479         return not gt
 480
 481     def __ge__(self, other):
 482         lt = self.__lt__(other)
 483         if lt is NotImplemented:
 484             return NotImplemented
 485         return not lt
 486
 487     def __lt__(self, other):
 488         if self._version != other._version:
 489             raise TypeError(
 490                 "%s and %s are not of the same version" % (str(self), str(other))
 491             )
 492         if not isinstance(other, _BaseIP):
 493             raise TypeError(
 494                 "%s and %s are not of the same type" % (str(self), str(other))
 495             )
 496         if self._ip != other._ip:
 497             return self._ip < other._ip
 498         return False
 499
 500     def __gt__(self, other):
 501         if self._version != other._version:
 502             raise TypeError(
 503                 "%s and %s are not of the same version" % (str(self), str(other))
 504             )
 505         if not isinstance(other, _BaseIP):
 506             raise TypeError(
 507                 "%s and %s are not of the same type" % (str(self), str(other))
 508             )
 509         if self._ip != other._ip:
 510             return self._ip > other._ip
 511         return False
 512
 513     # Shorthand for Integer addition and subtraction. This is not
 514     # meant to ever support addition/subtraction of addresses.
 515     def __add__(self, other):
 516         if not isinstance(other, int):
 517             return NotImplemented
 518         return IPAddress(int(self) + other, version=self._version)
 519
 520     def __sub__(self, other):
 521         if not isinstance(other, int):
 522             return NotImplemented
 523         return IPAddress(int(self) - other, version=self._version)
 524
 525     def __repr__(self):
 526         return "%s(%r)" % (self.__class__.__name__, str(self))
 527
 528     def __str__(self):
 529         return "%s" % self._string_from_ip_int(self._ip)
 530
 531     def __hash__(self):
 532         return hash(hex(int(self._ip)))
 533
 534     def _get_address_key(self):
 535         return (self._version, self)
 536
 537     @property
 538     def version(self):
 539         raise NotImplementedError("BaseIP has no version")
 540
 541
 542 class _BaseNet(_IPAddrBase):
 543
 544     """A generic IP object.
 545
 546     This IP class contains the version independent methods which are
 547     used by networks.
 548
 549     """
 550
 551     def __init__(self, address):
 552         self._cache = {}
 553
 554     def __repr__(self):
 555         return "%s(%r)" % (self.__class__.__name__, str(self))
 556
 557     def iterhosts(self):
 558         """Generate Iterator over usable hosts in a network.
 559
 560         This is like __iter__ except it doesn't return the network
 561         or broadcast addresses.
 562
 563         """
 564         cur = int(self.network) + 1
 565         bcast = int(self.broadcast) - 1
 566         while cur <= bcast:
 567             cur += 1
 568             yield IPAddress(cur - 1, version=self._version)
 569
 570     def __iter__(self):
 571         cur = int(self.network)
 572         bcast = int(self.broadcast)
 573         while cur <= bcast:
 574             cur += 1
 575             yield IPAddress(cur - 1, version=self._version)
 576
 577     def __getitem__(self, n):
 578         network = int(self.network)
 579         broadcast = int(self.broadcast)
 580         if n >= 0:
 581             if network + n > broadcast:
 582                 raise IndexError
 583             return IPAddress(network + n, version=self._version)
 584         else:
 585             n += 1
 586             if broadcast + n < network:
 587                 raise IndexError
 588             return IPAddress(broadcast + n, version=self._version)
 589
 590     def __lt__(self, other):
 591         if self._version != other._version:
 592             raise TypeError(
 593                 "%s and %s are not of the same version" % (str(self), str(other))
 594             )
 595         if not isinstance(other, _BaseNet):
 596             raise TypeError(
 597                 "%s and %s are not of the same type" % (str(self), str(other))
 598             )
 599         if self.network != other.network:
 600             return self.network < other.network
 601         if self.netmask != other.netmask:
 602             return self.netmask < other.netmask
 603         return False
 604
 605     def __gt__(self, other):
 606         if self._version != other._version:
 607             raise TypeError(
 608                 "%s and %s are not of the same version" % (str(self), str(other))
 609             )
 610         if not isinstance(other, _BaseNet):
 611             raise TypeError(
 612                 "%s and %s are not of the same type" % (str(self), str(other))
 613             )
 614         if self.network != other.network:
 615             return self.network > other.network
 616         if self.netmask != other.netmask:
 617             return self.netmask > other.netmask
 618         return False
 619
 620     def __le__(self, other):
 621         gt = self.__gt__(other)
 622         if gt is NotImplemented:
 623             return NotImplemented
 624         return not gt
 625
 626     def __ge__(self, other):
 627         lt = self.__lt__(other)
 628         if lt is NotImplemented:
 629             return NotImplemented
 630         return not lt
 631
 632     def __eq__(self, other):
 633         try:
 634             return (
 635                 self._version == other._version
 636                 and self.network == other.network
 637                 and int(self.netmask) == int(other.netmask)
 638             )
 639         except AttributeError:
 640             if isinstance(other, _BaseIP):
 641                 return self._version == other._version and self._ip == other._ip
 642
 643     def __ne__(self, other):
 644         eq = self.__eq__(other)
 645         if eq is NotImplemented:
 646             return NotImplemented
 647         return not eq
 648
 649     def __str__(self):
 650         return "%s/%s" % (str(self.ip), str(self._prefixlen))
 651
 652     def __hash__(self):
 653         return hash(int(self.network) ^ int(self.netmask))
 654
 655     def __contains__(self, other):
 656         # always false if one is v4 and the other is v6.
 657         if self._version != other._version:
 658             return False
 659         # dealing with another network.
 660         if isinstance(other, _BaseNet):
 661             return self.network <= other.network and self.broadcast >= other.broadcast
 662         # dealing with another address
 663         else:
 664             return int(self.network) <= int(other._ip) <= int(self.broadcast)
 665
 666     def overlaps(self, other):
 667         """Tell if self is partly contained in other."""
 668         return (
 669             self.network in other
 670             or self.broadcast in other
 671             or (other.network in self or other.broadcast in self)
 672         )
 673
 674     @property
 675     def network(self):
 676         x = self._cache.get("network")
 677         if x is None:
 678             x = IPAddress(self._ip & int(self.netmask), version=self._version)
 679             self._cache["network"] = x
 680         return x
 681
 682     @property
 683     def broadcast(self):
 684         x = self._cache.get("broadcast")
 685         if x is None:
 686             x = IPAddress(self._ip | int(self.hostmask), version=self._version)
 687             self._cache["broadcast"] = x
 688         return x
 689
 690     @property
 691     def hostmask(self):
 692         x = self._cache.get("hostmask")
 693         if x is None:
 694             x = IPAddress(int(self.netmask) ^ self._ALL_ONES, version=self._version)
 695             self._cache["hostmask"] = x
 696         return x
 697
 698     @property
 699     def with_prefixlen(self):
 700         return "%s/%d" % (str(self.ip), self._prefixlen)
 701
 702     @property
 703     def with_netmask(self):
 704         return "%s/%s" % (str(self.ip), str(self.netmask))
 705
 706     @property
 707     def with_hostmask(self):
 708         return "%s/%s" % (str(self.ip), str(self.hostmask))
 709
 710     @property
 711     def numhosts(self):
 712         """Number of hosts in the current subnet."""
 713         return int(self.broadcast) - int(self.network) + 1
 714
 715     @property
 716     def version(self):
 717         raise NotImplementedError("BaseNet has no version")
 718
 719     @property
 720     def prefixlen(self):
 721         return self._prefixlen
 722
 723     def address_exclude(self, other):
 724         """Remove an address from a larger block.
 725
 726         For example:
 727
 728             addr1 = IPNetwork('10.1.1.0/24')
 729             addr2 = IPNetwork('10.1.1.0/26')
 730             addr1.address_exclude(addr2) =
 731                 [IPNetwork('10.1.1.64/26'), IPNetwork('10.1.1.128/25')]
 732
 733         or IPv6:
 734
 735             addr1 = IPNetwork('::1/32')
 736             addr2 = IPNetwork('::1/128')
 737             addr1.address_exclude(addr2) = [IPNetwork('::0/128'),
 738                 IPNetwork('::2/127'),
 739                 IPNetwork('::4/126'),
 740                 IPNetwork('::8/125'),
 741                 ...
 742                 IPNetwork('0:0:8000::/33')]
 743
 744         Args:
 745             other: An IPvXNetwork object of the same type.
 746
 747         Returns:
 748             A sorted list of IPvXNetwork objects addresses which is self
 749             minus other.
 750
 751         Raises:
 752             TypeError: If self and other are of difffering address
 753               versions, or if other is not a network object.
 754             ValueError: If other is not completely contained by self.
 755
 756         """
 757         if not self._version == other._version:
 758             raise TypeError(
 759                 "%s and %s are not of the same version" % (str(self), str(other))
 760             )
 761
 762         if not isinstance(other, _BaseNet):
 763             raise TypeError("%s is not a network object" % str(other))
 764
 765         if other not in self:
 766             raise ValueError("%s not contained in %s" % (str(other), str(self)))
 767         if other == self:
 768             return []
 769
 770         ret_addrs = []
 771
 772         # Make sure we're comparing the network of other.
 773         other = IPNetwork(
 774             "%s/%s" % (str(other.network), str(other.prefixlen)), version=other._version
 775         )
 776
 777         s1, s2 = self.subnet()
 778         while s1 != other and s2 != other:
 779             if other in s1:
 780                 ret_addrs.append(s2)
 781                 s1, s2 = s1.subnet()
 782             elif other in s2:
 783                 ret_addrs.append(s1)
 784                 s1, s2 = s2.subnet()
 785             else:
 786                 # If we got here, there's a bug somewhere.
 787                 assert (
 788                     False
 789                 ), "Error performing exclusion: " "s1: %s s2: %s other: %s" % (
 790                     str(s1),
 791                     str(s2),
 792                     str(other),
 793                 )
 794         if s1 == other:
 795             ret_addrs.append(s2)
 796         elif s2 == other:
 797             ret_addrs.append(s1)
 798         else:
 799             # If we got here, there's a bug somewhere.
 800             assert False, "Error performing exclusion: " "s1: %s s2: %s other: %s" % (
 801                 str(s1),
 802                 str(s2),
 803                 str(other),
 804             )
 805
 806         return sorted(ret_addrs, key=_BaseNet._get_networks_key)
 807
 808     def compare_networks(self, other):
 809         """Compare two IP objects.
 810
 811         This is only concerned about the comparison of the integer
 812         representation of the network addresses.  This means that the
 813         host bits aren't considered at all in this method.  If you want
 814         to compare host bits, you can easily enough do a
 815         'HostA._ip < HostB._ip'
 816
 817         Args:
 818             other: An IP object.
 819
 820         Returns:
 821             If the IP versions of self and other are the same, returns:
 822
 823             -1 if self < other:
 824               eg: IPv4('1.1.1.0/24') < IPv4('1.1.2.0/24')
 825               IPv6('1080::200C:417A') < IPv6('1080::200B:417B')
 826             0 if self == other
 827               eg: IPv4('1.1.1.1/24') == IPv4('1.1.1.2/24')
 828               IPv6('1080::200C:417A/96') == IPv6('1080::200C:417B/96')
 829             1 if self > other
 830               eg: IPv4('1.1.1.0/24') > IPv4('1.1.0.0/24')
 831               IPv6('1080::1:200C:417A/112') >
 832               IPv6('1080::0:200C:417A/112')
 833
 834             If the IP versions of self and other are different, returns:
 835
 836             -1 if self._version < other._version
 837               eg: IPv4('10.0.0.1/24') < IPv6('::1/128')
 838             1 if self._version > other._version
 839               eg: IPv6('::1/128') > IPv4('255.255.255.0/24')
 840
 841         """
 842         if self._version < other._version:
 843             return -1
 844         if self._version > other._version:
 845             return 1
 846         # self._version == other._version below here:
 847         if self.network < other.network:
 848             return -1
 849         if self.network > other.network:
 850             return 1
 851         # self.network == other.network below here:
 852         if self.netmask < other.netmask:
 853             return -1
 854         if self.netmask > other.netmask:
 855             return 1
 856         # self.network == other.network and self.netmask == other.netmask
 857         return 0
 858
 859     def _get_networks_key(self):
 860         """Network-only key function.
 861
 862         Returns an object that identifies this address' network and
 863         netmask. This function is a suitable "key" argument for sorted()
 864         and list.sort().
 865
 866         """
 867         return (self._version, self.network, self.netmask)
 868
 869     def _ip_int_from_prefix(self, prefixlen):
 870         """Turn the prefix length into a bitwise netmask.
 871
 872         Args:
 873             prefixlen: An integer, the prefix length.
 874
 875         Returns:
 876             An integer.
 877
 878         """
 879         return self._ALL_ONES ^ (self._ALL_ONES >> prefixlen)
 880
 881     def _prefix_from_ip_int(self, ip_int):
 882         """Return prefix length from a bitwise netmask.
 883
 884         Args:
 885             ip_int: An integer, the netmask in expanded bitwise format.
 886
 887         Returns:
 888             An integer, the prefix length.
 889
 890         Raises:
 891             NetmaskValueError: If the input is not a valid netmask.
 892
 893         """
 894         prefixlen = self._max_prefixlen
 895         while prefixlen:
 896             if ip_int & 1:
 897                 break
 898             ip_int >>= 1
 899             prefixlen -= 1
 900
 901         if ip_int == (1 << prefixlen) - 1:
 902             return prefixlen
 903         else:
 904             raise NetmaskValueError("Bit pattern does not match /1*0*/")
 905
 906     def _prefix_from_prefix_string(self, prefixlen_str):
 907         """Turn a prefix length string into an integer.
 908
 909         Args:
 910             prefixlen_str: A decimal string containing the prefix length.
 911
 912         Returns:
 913             The prefix length as an integer.
 914
 915         Raises:
 916             NetmaskValueError: If the input is malformed or out of range.
 917
 918         """
 919         try:
 920             if not _BaseV4._DECIMAL_DIGITS.issuperset(prefixlen_str):
 921                 raise ValueError
 922             prefixlen = int(prefixlen_str)
 923             if not (0 <= prefixlen <= self._max_prefixlen):
 924                 raise ValueError
 925         except ValueError:
 926             raise NetmaskValueError("%s is not a valid prefix length" % prefixlen_str)
 927         return prefixlen
 928
 929     def _prefix_from_ip_string(self, ip_str):
 930         """Turn a netmask/hostmask string into a prefix length.
 931
 932         Args:
 933             ip_str: A netmask or hostmask, formatted as an IP address.
 934
 935         Returns:
 936             The prefix length as an integer.
 937
 938         Raises:
 939             NetmaskValueError: If the input is not a netmask or hostmask.
 940
 941         """
 942         # Parse the netmask/hostmask like an IP address.
 943         try:
 944             ip_int = self._ip_int_from_string(ip_str)
 945         except AddressValueError:
 946             raise NetmaskValueError("%s is not a valid netmask" % ip_str)
 947
 948         # Try matching a netmask (this would be /1*0*/ as a bitwise regexp).
 949         # Note that the two ambiguous cases (all-ones and all-zeroes) are
 950         # treated as netmasks.
 951         try:
 952             return self._prefix_from_ip_int(ip_int)
 953         except NetmaskValueError:
 954             pass
 955
 956         # Invert the bits, and try matching a /0+1+/ hostmask instead.
 957         ip_int ^= self._ALL_ONES
 958         try:
 959             return self._prefix_from_ip_int(ip_int)
 960         except NetmaskValueError:
 961             raise NetmaskValueError("%s is not a valid netmask" % ip_str)
 962
 963     def iter_subnets(self, prefixlen_diff=1, new_prefix=None):
 964         """The subnets which join to make the current subnet.
 965
 966         In the case that self contains only one IP
 967         (self._prefixlen == 32 for IPv4 or self._prefixlen == 128
 968         for IPv6), return a list with just ourself.
 969
 970         Args:
 971             prefixlen_diff: An integer, the amount the prefix length
 972               should be increased by. This should not be set if
 973               new_prefix is also set.
 974             new_prefix: The desired new prefix length. This must be a
 975               larger number (smaller prefix) than the existing prefix.
 976               This should not be set if prefixlen_diff is also set.
 977
 978         Returns:
 979             An iterator of IPv(4|6) objects.
 980
 981         Raises:
 982             ValueError: The prefixlen_diff is too small or too large.
 983                 OR
 984             prefixlen_diff and new_prefix are both set or new_prefix
 985               is a smaller number than the current prefix (smaller
 986               number means a larger network)
 987
 988         """
 989         if self._prefixlen == self._max_prefixlen:
 990             yield self
 991             return
 992
 993         if new_prefix is not None:
 994             if new_prefix < self._prefixlen:
 995                 raise ValueError("new prefix must be longer")
 996             if prefixlen_diff != 1:
 997                 raise ValueError("cannot set prefixlen_diff and new_prefix")
 998             prefixlen_diff = new_prefix - self._prefixlen
 999
1000         if prefixlen_diff < 0:
1001             raise ValueError("prefix length diff must be > 0")
1002         new_prefixlen = self._prefixlen + prefixlen_diff
1003
1004         if new_prefixlen > self._max_prefixlen:
1005             raise ValueError(
1006                 "prefix length diff %d is invalid for netblock %s"
1007                 % (new_prefixlen, str(self))
1008             )
1009
1010         first = IPNetwork(
1011             "%s/%s" % (str(self.network), str(self._prefixlen + prefixlen_diff)),
1012             version=self._version,
1013         )
1014
1015         yield first
1016         current = first
1017         while True:
1018             broadcast = current.broadcast
1019             if broadcast == self.broadcast:
1020                 return
1021             new_addr = IPAddress(int(broadcast) + 1, version=self._version)
1022             current = IPNetwork(
1023                 "%s/%s" % (str(new_addr), str(new_prefixlen)), version=self._version
1024             )
1025
1026             yield current
1027
1028     def masked(self):
1029         """Return the network object with the host bits masked out."""
1030         return IPNetwork(
1031             "%s/%d" % (self.network, self._prefixlen), version=self._version
1032         )
1033
1034     def subnet(self, prefixlen_diff=1, new_prefix=None):
1035         """Return a list of subnets, rather than an iterator."""
1036         return list(self.iter_subnets(prefixlen_diff, new_prefix))
1037
1038     def supernet(self, prefixlen_diff=1, new_prefix=None):
1039         """The supernet containing the current network.
1040
1041         Args:
1042             prefixlen_diff: An integer, the amount the prefix length of
1043               the network should be decreased by.  For example, given a
1044               /24 network and a prefixlen_diff of 3, a supernet with a
1045               /21 netmask is returned.
1046
1047         Returns:
1048             An IPv4 network object.
1049
1050         Raises:
1051             ValueError: If self.prefixlen - prefixlen_diff < 0. I.e., you have a
1052               negative prefix length.
1053                 OR
1054             If prefixlen_diff and new_prefix are both set or new_prefix is a
1055               larger number than the current prefix (larger number means a
1056               smaller network)
1057
1058         """
1059         if self._prefixlen == 0:
1060             return self
1061
1062         if new_prefix is not None:
1063             if new_prefix > self._prefixlen:
1064                 raise ValueError("new prefix must be shorter")
1065             if prefixlen_diff != 1:
1066                 raise ValueError("cannot set prefixlen_diff and new_prefix")
1067             prefixlen_diff = self._prefixlen - new_prefix
1068
1069         if self.prefixlen - prefixlen_diff < 0:
1070             raise ValueError(
1071                 "current prefixlen is %d, cannot have a prefixlen_diff of %d"
1072                 % (self.prefixlen, prefixlen_diff)
1073             )
1074         return IPNetwork(
1075             "%s/%s" % (str(self.network), str(self.prefixlen - prefixlen_diff)),
1076             version=self._version,
1077         )
1078
1079     # backwards compatibility
1080     Subnet = subnet
1081     Supernet = supernet
1082     AddressExclude = address_exclude
1083     CompareNetworks = compare_networks
1084     Contains = __contains__
1085
1086
1087 class _BaseV4(object):
1088
1089     """Base IPv4 object.
1090
1091     The following methods are used by IPv4 objects in both single IP
1092     addresses and networks.
1093
1094     """
1095
1096     # Equivalent to 255.255.255.255 or 32 bits of 1's.
1097     _ALL_ONES = (2**IPV4LENGTH) - 1
1098     _DECIMAL_DIGITS = frozenset("0123456789")
1099
1100     def __init__(self, address):
1101         self._version = 4
1102         self._max_prefixlen = IPV4LENGTH
1103
1104     def _explode_shorthand_ip_string(self):
1105         return str(self)
1106
1107     def _ip_int_from_string(self, ip_str):
1108         """Turn the given IP string into an integer for comparison.
1109
1110         Args:
1111             ip_str: A string, the IP ip_str.
1112
1113         Returns:
1114             The IP ip_str as an integer.
1115
1116         Raises:
1117             AddressValueError: if ip_str isn't a valid IPv4 Address.
1118
1119         """
1120         octets = ip_str.split(".")
1121         if len(octets) != 4:
1122             raise AddressValueError(ip_str)
1123
1124         packed_ip = 0
1125         for oc in octets:
1126             try:
1127                 packed_ip = (packed_ip << 8) | self._parse_octet(oc)
1128             except ValueError:
1129                 raise AddressValueError(ip_str)
1130         return packed_ip
1131
1132     def _parse_octet(self, octet_str):
1133         """Convert a decimal octet into an integer.
1134
1135         Args:
1136             octet_str: A string, the number to parse.
1137
1138         Returns:
1139             The octet as an integer.
1140
1141         Raises:
1142             ValueError: if the octet isn't strictly a decimal from [0..255].
1143
1144         """
1145         # Whitelist the characters, since int() allows a lot of bizarre stuff.
1146         if not self._DECIMAL_DIGITS.issuperset(octet_str):
1147             raise ValueError
1148         octet_int = int(octet_str, 10)
1149         # Disallow leading zeroes, because no clear standard exists on
1150         # whether these should be interpreted as decimal or octal.
1151         if octet_int > 255 or (octet_str[0] == "0" and len(octet_str) > 1):
1152             raise ValueError
1153         return octet_int
1154
1155     def _string_from_ip_int(self, ip_int):
1156         """Turns a 32-bit integer into dotted decimal notation.
1157
1158         Args:
1159             ip_int: An integer, the IP address.
1160
1161         Returns:
1162             The IP address as a string in dotted decimal notation.
1163
1164         """
1165         octets = []
1166         for _ in range(4):
1167             octets.insert(0, str(ip_int & 0xFF))
1168             ip_int >>= 8
1169         return ".".join(octets)
1170
1171     @property
1172     def max_prefixlen(self):
1173         return self._max_prefixlen
1174
1175     @property
1176     def packed(self):
1177         """The binary representation of this address."""
1178         return v4_int_to_packed(self._ip)
1179
1180     @property
1181     def version(self):
1182         return self._version
1183
1184     @property
1185     def is_reserved(self):
1186         """Test if the address is otherwise IETF reserved.
1187
1188         Returns:
1189             A boolean, True if the address is within the
1190             reserved IPv4 Network range.
1191
1192         """
1193         return self in IPv4Network("240.0.0.0/4")
1194
1195     @property
1196     def is_private(self):
1197         """Test if this address is allocated for private networks.
1198
1199         Returns:
1200             A boolean, True if the address is reserved per RFC 1918.
1201
1202         """
1203         return (
1204             self in IPv4Network("10.0.0.0/8")
1205             or self in IPv4Network("172.16.0.0/12")
1206             or self in IPv4Network("192.168.0.0/16")
1207         )
1208
1209     @property
1210     def is_multicast(self):
1211         """Test if the address is reserved for multicast use.
1212
1213         Returns:
1214             A boolean, True if the address is multicast.
1215             See RFC 3171 for details.
1216
1217         """
1218         return self in IPv4Network("224.0.0.0/4")
1219
1220     @property
1221     def is_unspecified(self):
1222         """Test if the address is unspecified.
1223
1224         Returns:
1225             A boolean, True if this is the unspecified address as defined in
1226             RFC 5735 3.
1227
1228         """
1229         return self in IPv4Network("0.0.0.0")
1230
1231     @property
1232     def is_loopback(self):
1233         """Test if the address is a loopback address.
1234
1235         Returns:
1236             A boolean, True if the address is a loopback per RFC 3330.
1237
1238         """
1239         return self in IPv4Network("127.0.0.0/8")
1240
1241     @property
1242     def is_link_local(self):
1243         """Test if the address is reserved for link-local.
1244
1245         Returns:
1246             A boolean, True if the address is link-local per RFC 3927.
1247
1248         """
1249         return self in IPv4Network("169.254.0.0/16")
1250
1251
1252 class IPv4Address(_BaseV4, _BaseIP):
1253
1254     """Represent and manipulate single IPv4 Addresses."""
1255
1256     def __init__(self, address):
1257         """
1258         Args:
1259             address: A string or integer representing the IP
1260               '192.168.1.1'
1261
1262               Additionally, an integer can be passed, so
1263               IPv4Address('192.168.1.1') == IPv4Address(3232235777).
1264               or, more generally
1265               IPv4Address(int(IPv4Address('192.168.1.1'))) ==
1266                 IPv4Address('192.168.1.1')
1267
1268         Raises:
1269             AddressValueError: If ipaddr isn't a valid IPv4 address.
1270
1271         """
1272         _BaseV4.__init__(self, address)
1273
1274         # Efficient constructor from integer.
1275         if isinstance(address, int):
1276             self._ip = address
1277             if address < 0 or address > self._ALL_ONES:
1278                 raise AddressValueError(address)
1279             return
1280
1281         # Constructing from a packed address
1282         if isinstance(address, Bytes):
1283             try:
1284                 (self._ip,) = struct.unpack("!I", address)
1285             except struct.error:
1286                 raise AddressValueError(address)  # Wrong length.
1287             return
1288
1289         # Assume input argument to be string or any object representation
1290         # which converts into a formatted IP string.
1291         addr_str = str(address)
1292         self._ip = self._ip_int_from_string(addr_str)
1293
1294
1295 class IPv4Network(_BaseV4, _BaseNet):
1296
1297     """This class represents and manipulates 32-bit IPv4 networks.
1298
1299     Attributes: [examples for IPv4Network('1.2.3.4/27')]
1300         ._ip: 16909060
1301         .ip: IPv4Address('1.2.3.4')
1302         .network: IPv4Address('1.2.3.0')
1303         .hostmask: IPv4Address('0.0.0.31')
1304         .broadcast: IPv4Address('1.2.3.31')
1305         .netmask: IPv4Address('255.255.255.224')
1306         .prefixlen: 27
1307
1308     """
1309
1310     def __init__(self, address, strict=False):
1311         """Instantiate a new IPv4 network object.
1312
1313         Args:
1314             address: A string or integer representing the IP [& network].
1315               '192.168.1.1/24'
1316               '192.168.1.1/255.255.255.0'
1317               '192.168.1.1/0.0.0.255'
1318               are all functionally the same in IPv4. Similarly,
1319               '192.168.1.1'
1320               '192.168.1.1/255.255.255.255'
1321               '192.168.1.1/32'
1322               are also functionaly equivalent. That is to say, failing to
1323               provide a subnetmask will create an object with a mask of /32.
1324
1325               If the mask (portion after the / in the argument) is given in
1326               dotted quad form, it is treated as a netmask if it starts with a
1327               non-zero field (e.g. /255.0.0.0 == /8) and as a hostmask if it
1328               starts with a zero field (e.g. 0.255.255.255 == /8), with the
1329               single exception of an all-zero mask which is treated as a
1330               netmask == /0. If no mask is given, a default of /32 is used.
1331
1332               Additionally, an integer can be passed, so
1333               IPv4Network('192.168.1.1') == IPv4Network(3232235777).
1334               or, more generally
1335               IPv4Network(int(IPv4Network('192.168.1.1'))) ==
1336                 IPv4Network('192.168.1.1')
1337
1338             strict: A boolean. If true, ensure that we have been passed
1339               A true network address, eg, 192.168.1.0/24 and not an
1340               IP address on a network, eg, 192.168.1.1/24.
1341
1342         Raises:
1343             AddressValueError: If ipaddr isn't a valid IPv4 address.
1344             NetmaskValueError: If the netmask isn't valid for
1345               an IPv4 address.
1346             ValueError: If strict was True and a network address was not
1347               supplied.
1348
1349         """
1350         _BaseNet.__init__(self, address)
1351         _BaseV4.__init__(self, address)
1352
1353         # Constructing from an integer or packed bytes.
1354         if isinstance(address, (int, Bytes)):
1355             self.ip = IPv4Address(address)
1356             self._ip = self.ip._ip
1357             self._prefixlen = self._max_prefixlen
1358             self.netmask = IPv4Address(self._ALL_ONES)
1359             return
1360
1361         # Assume input argument to be string or any object representation
1362         # which converts into a formatted IP prefix string.
1363         addr = str(address).split("/")
1364
1365         if len(addr) > 2:
1366             raise AddressValueError(address)
1367
1368         self._ip = self._ip_int_from_string(addr[0])
1369         self.ip = IPv4Address(self._ip)
1370
1371         if len(addr) == 2:
1372             try:
1373                 # Check for a netmask in prefix length form.
1374                 self._prefixlen = self._prefix_from_prefix_string(addr[1])
1375             except NetmaskValueError:
1376                 # Check for a netmask or hostmask in dotted-quad form.
1377                 # This may raise NetmaskValueError.
1378                 self._prefixlen = self._prefix_from_ip_string(addr[1])
1379         else:
1380             self._prefixlen = self._max_prefixlen
1381
1382         self.netmask = IPv4Address(self._ip_int_from_prefix(self._prefixlen))
1383
1384         if strict:
1385             if self.ip != self.network:
1386                 raise ValueError("%s has host bits set" % self.ip)
1387         if self._prefixlen == (self._max_prefixlen - 1):
1388             self.iterhosts = self.__iter__
1389
1390     # backwards compatibility
1391     def IsRFC1918(self):
1392         return self.is_private
1393
1394     def IsMulticast(self):
1395         return self.is_multicast
1396
1397     def IsLoopback(self):
1398         return self.is_loopback
1399
1400     def IsLinkLocal(self):
1401         return self.is_link_local
1402
1403
1404 class _BaseV6(object):
1405
1406     """Base IPv6 object.
1407
1408     The following methods are used by IPv6 objects in both single IP
1409     addresses and networks.
1410
1411     """
1412
1413     _ALL_ONES = (2**IPV6LENGTH) - 1
1414     _HEXTET_COUNT = 8
1415     _HEX_DIGITS = frozenset("0123456789ABCDEFabcdef")
1416
1417     def __init__(self, address):
1418         self._version = 6
1419         self._max_prefixlen = IPV6LENGTH
1420
1421     def _ip_int_from_string(self, ip_str):
1422         """Turn an IPv6 ip_str into an integer.
1423
1424         Args:
1425             ip_str: A string, the IPv6 ip_str.
1426
1427         Returns:
1428             A long, the IPv6 ip_str.
1429
1430         Raises:
1431             AddressValueError: if ip_str isn't a valid IPv6 Address.
1432
1433         """
1434         parts = ip_str.split(":")
1435
1436         # An IPv6 address needs at least 2 colons (3 parts).
1437         if len(parts) < 3:
1438             raise AddressValueError(ip_str)
1439
1440         # If the address has an IPv4-style suffix, convert it to hexadecimal.
1441         if "." in parts[-1]:
1442             ipv4_int = IPv4Address(parts.pop())._ip
1443             parts.append("%x" % ((ipv4_int >> 16) & 0xFFFF))
1444             parts.append("%x" % (ipv4_int & 0xFFFF))
1445
1446         # An IPv6 address can't have more than 8 colons (9 parts).
1447         if len(parts) > self._HEXTET_COUNT + 1:
1448             raise AddressValueError(ip_str)
1449
1450         # Disregarding the endpoints, find '::' with nothing in between.
1451         # This indicates that a run of zeroes has been skipped.
1452         try:
1453             (skip_index,) = [i for i in range(1, len(parts) - 1) if not parts[i]] or [
1454                 None
1455             ]
1456         except ValueError:
1457             # Can't have more than one '::'
1458             raise AddressValueError(ip_str)
1459
1460         # parts_hi is the number of parts to copy from above/before the '::'
1461         # parts_lo is the number of parts to copy from below/after the '::'
1462         if skip_index is not None:
1463             # If we found a '::', then check if it also covers the endpoints.
1464             parts_hi = skip_index
1465             parts_lo = len(parts) - skip_index - 1
1466             if not parts[0]:
1467                 parts_hi -= 1
1468                 if parts_hi:
1469                     raise AddressValueError(ip_str)  # ^: requires ^::
1470             if not parts[-1]:
1471                 parts_lo -= 1
1472                 if parts_lo:
1473                     raise AddressValueError(ip_str)  # :$ requires ::$
1474             parts_skipped = self._HEXTET_COUNT - (parts_hi + parts_lo)
1475             if parts_skipped < 1:
1476                 raise AddressValueError(ip_str)
1477         else:
1478             # Otherwise, allocate the entire address to parts_hi.  The endpoints
1479             # could still be empty, but _parse_hextet() will check for that.
1480             if len(parts) != self._HEXTET_COUNT:
1481                 raise AddressValueError(ip_str)
1482             parts_hi = len(parts)
1483             parts_lo = 0
1484             parts_skipped = 0
1485
1486         try:
1487             # Now, parse the hextets into a 128-bit integer.
1488             ip_int = 0
1489             for i in range(parts_hi):
1490                 ip_int <<= 16
1491                 ip_int |= self._parse_hextet(parts[i])
1492             ip_int <<= 16 * parts_skipped
1493             for i in range(-parts_lo, 0):
1494                 ip_int <<= 16
1495                 ip_int |= self._parse_hextet(parts[i])
1496             return ip_int
1497         except ValueError:
1498             raise AddressValueError(ip_str)
1499
1500     def _parse_hextet(self, hextet_str):
1501         """Convert an IPv6 hextet string into an integer.
1502
1503         Args:
1504             hextet_str: A string, the number to parse.
1505
1506         Returns:
1507             The hextet as an integer.
1508
1509         Raises:
1510             ValueError: if the input isn't strictly a hex number from [0..FFFF].
1511
1512         """
1513         # Whitelist the characters, since int() allows a lot of bizarre stuff.
1514         if not self._HEX_DIGITS.issuperset(hextet_str):
1515             raise ValueError
1516         if len(hextet_str) > 4:
1517             raise ValueError
1518         hextet_int = int(hextet_str, 16)
1519         if hextet_int > 0xFFFF:
1520             raise ValueError
1521         return hextet_int
1522
1523     def _compress_hextets(self, hextets):
1524         """Compresses a list of hextets.
1525
1526         Compresses a list of strings, replacing the longest continuous
1527         sequence of "0" in the list with "" and adding empty strings at
1528         the beginning or at the end of the string such that subsequently
1529         calling ":".join(hextets) will produce the compressed version of
1530         the IPv6 address.
1531
1532         Args:
1533             hextets: A list of strings, the hextets to compress.
1534
1535         Returns:
1536             A list of strings.
1537
1538         """
1539         best_doublecolon_start = -1
1540         best_doublecolon_len = 0
1541         doublecolon_start = -1
1542         doublecolon_len = 0
1543         for index in range(len(hextets)):
1544             if hextets[index] == "0":
1545                 doublecolon_len += 1
1546                 if doublecolon_start == -1:
1547                     # Start of a sequence of zeros.
1548                     doublecolon_start = index
1549                 if doublecolon_len > best_doublecolon_len:
1550                     # This is the longest sequence of zeros so far.
1551                     best_doublecolon_len = doublecolon_len
1552                     best_doublecolon_start = doublecolon_start
1553             else:
1554                 doublecolon_len = 0
1555                 doublecolon_start = -1
1556
1557         if best_doublecolon_len > 1:
1558             best_doublecolon_end = best_doublecolon_start + best_doublecolon_len
1559             # For zeros at the end of the address.
1560             if best_doublecolon_end == len(hextets):
1561                 hextets += [""]
1562             hextets[best_doublecolon_start:best_doublecolon_end] = [""]
1563             # For zeros at the beginning of the address.
1564             if best_doublecolon_start == 0:
1565                 hextets = [""] + hextets
1566
1567         return hextets
1568
1569     def _string_from_ip_int(self, ip_int=None):
1570         """Turns a 128-bit integer into hexadecimal notation.
1571
1572         Args:
1573             ip_int: An integer, the IP address.
1574
1575         Returns:
1576             A string, the hexadecimal representation of the address.
1577
1578         Raises:
1579             ValueError: The address is bigger than 128 bits of all ones.
1580
1581         """
1582         if not ip_int and ip_int != 0:
1583             ip_int = int(self._ip)
1584
1585         if ip_int > self._ALL_ONES:
1586             raise ValueError("IPv6 address is too large")
1587
1588         hex_str = "%032x" % ip_int
1589         hextets = []
1590         for x in range(0, 32, 4):
1591             hextets.append("%x" % int(hex_str[x : x + 4], 16))
1592
1593         hextets = self._compress_hextets(hextets)
1594         return ":".join(hextets)
1595
1596     def _explode_shorthand_ip_string(self):
1597         """Expand a shortened IPv6 address.
1598
1599         Args:
1600             ip_str: A string, the IPv6 address.
1601
1602         Returns:
1603             A string, the expanded IPv6 address.
1604
1605         """
1606         if isinstance(self, _BaseNet):
1607             ip_str = str(self.ip)
1608         else:
1609             ip_str = str(self)
1610
1611         ip_int = self._ip_int_from_string(ip_str)
1612         parts = []
1613         for i in range(self._HEXTET_COUNT):
1614             parts.append("%04x" % (ip_int & 0xFFFF))
1615             ip_int >>= 16
1616         parts.reverse()
1617         if isinstance(self, _BaseNet):
1618             return "%s/%d" % (":".join(parts), self.prefixlen)
1619         return ":".join(parts)
1620
1621     @property
1622     def max_prefixlen(self):
1623         return self._max_prefixlen
1624
1625     @property
1626     def packed(self):
1627         """The binary representation of this address."""
1628         return v6_int_to_packed(self._ip)
1629
1630     @property
1631     def version(self):
1632         return self._version
1633
1634     @property
1635     def is_multicast(self):
1636         """Test if the address is reserved for multicast use.
1637
1638         Returns:
1639             A boolean, True if the address is a multicast address.
1640             See RFC 2373 2.7 for details.
1641
1642         """
1643         return self in IPv6Network("ff00::/8")
1644
1645     @property
1646     def is_reserved(self):
1647         """Test if the address is otherwise IETF reserved.
1648
1649         Returns:
1650             A boolean, True if the address is within one of the
1651             reserved IPv6 Network ranges.
1652
1653         """
1654         return (
1655             self in IPv6Network("::/8")
1656             or self in IPv6Network("100::/8")
1657             or self in IPv6Network("200::/7")
1658             or self in IPv6Network("400::/6")
1659             or self in IPv6Network("800::/5")
1660             or self in IPv6Network("1000::/4")
1661             or self in IPv6Network("4000::/3")
1662             or self in IPv6Network("6000::/3")
1663             or self in IPv6Network("8000::/3")
1664             or self in IPv6Network("A000::/3")
1665             or self in IPv6Network("C000::/3")
1666             or self in IPv6Network("E000::/4")
1667             or self in IPv6Network("F000::/5")
1668             or self in IPv6Network("F800::/6")
1669             or self in IPv6Network("FE00::/9")
1670         )
1671
1672     @property
1673     def is_unspecified(self):
1674         """Test if the address is unspecified.
1675
1676         Returns:
1677             A boolean, True if this is the unspecified address as defined in
1678             RFC 2373 2.5.2.
1679
1680         """
1681         return self._ip == 0 and getattr(self, "_prefixlen", 128) == 128
1682
1683     @property
1684     def is_loopback(self):
1685         """Test if the address is a loopback address.
1686
1687         Returns:
1688             A boolean, True if the address is a loopback address as defined in
1689             RFC 2373 2.5.3.
1690
1691         """
1692         return self._ip == 1 and getattr(self, "_prefixlen", 128) == 128
1693
1694     @property
1695     def is_link_local(self):
1696         """Test if the address is reserved for link-local.
1697
1698         Returns:
1699             A boolean, True if the address is reserved per RFC 4291.
1700
1701         """
1702         return self in IPv6Network("fe80::/10")
1703
1704     @property
1705     def is_site_local(self):
1706         """Test if the address is reserved for site-local.
1707
1708         Note that the site-local address space has been deprecated by RFC 3879.
1709         Use is_private to test if this address is in the space of unique local
1710         addresses as defined by RFC 4193.
1711
1712         Returns:
1713             A boolean, True if the address is reserved per RFC 3513 2.5.6.
1714
1715         """
1716         return self in IPv6Network("fec0::/10")
1717
1718     @property
1719     def is_private(self):
1720         """Test if this address is allocated for private networks.
1721
1722         Returns:
1723             A boolean, True if the address is reserved per RFC 4193.
1724
1725         """
1726         return self in IPv6Network("fc00::/7")
1727
1728     @property
1729     def ipv4_mapped(self):
1730         """Return the IPv4 mapped address.
1731
1732         Returns:
1733             If the IPv6 address is a v4 mapped address, return the
1734             IPv4 mapped address. Return None otherwise.
1735
1736         """
1737         if (self._ip >> 32) != 0xFFFF:
1738             return None
1739         return IPv4Address(self._ip & 0xFFFFFFFF)
1740
1741     @property
1742     def teredo(self):
1743         """Tuple of embedded teredo IPs.
1744
1745         Returns:
1746             Tuple of the (server, client) IPs or None if the address
1747             doesn't appear to be a teredo address (doesn't start with
1748             2001::/32)
1749
1750         """
1751         if (self._ip >> 96) != 0x20010000:
1752             return None
1753         return (
1754             IPv4Address((self._ip >> 64) & 0xFFFFFFFF),
1755             IPv4Address(~self._ip & 0xFFFFFFFF),
1756         )
1757
1758     @property
1759     def sixtofour(self):
1760         """Return the IPv4 6to4 embedded address.
1761
1762         Returns:
1763             The IPv4 6to4-embedded address if present or None if the
1764             address doesn't appear to contain a 6to4 embedded address.
1765
1766         """
1767         if (self._ip >> 112) != 0x2002:
1768             return None
1769         return IPv4Address((self._ip >> 80) & 0xFFFFFFFF)
1770
1771
1772 class IPv6Address(_BaseV6, _BaseIP):
1773
1774     """Represent and manipulate single IPv6 Addresses."""
1775
1776     def __init__(self, address):
1777         """Instantiate a new IPv6 address object.
1778
1779         Args:
1780             address: A string or integer representing the IP
1781
1782               Additionally, an integer can be passed, so
1783               IPv6Address('2001:4860::') ==
1784                 IPv6Address(42541956101370907050197289607612071936L).
1785               or, more generally
1786               IPv6Address(IPv6Address('2001:4860::')._ip) ==
1787                 IPv6Address('2001:4860::')
1788
1789         Raises:
1790             AddressValueError: If address isn't a valid IPv6 address.
1791
1792         """
1793         _BaseV6.__init__(self, address)
1794
1795         # Efficient constructor from integer.
1796         if isinstance(address, int):
1797             self._ip = address
1798             if address < 0 or address > self._ALL_ONES:
1799                 raise AddressValueError(address)
1800             return
1801
1802         # Constructing from a packed address
1803         if isinstance(address, Bytes):
1804             try:
1805                 hi, lo = struct.unpack("!QQ", address)
1806             except struct.error:
1807                 raise AddressValueError(address)  # Wrong length.
1808             self._ip = (hi << 64) | lo
1809             return
1810
1811         # Assume input argument to be string or any object representation
1812         # which converts into a formatted IP string.
1813         addr_str = str(address)
1814         if not addr_str:
1815             raise AddressValueError("")
1816
1817         self._ip = self._ip_int_from_string(addr_str)
1818
1819
1820 class IPv6Network(_BaseV6, _BaseNet):
1821
1822     """This class represents and manipulates 128-bit IPv6 networks.
1823
1824     Attributes: [examples for IPv6('2001:658:22A:CAFE:200::1/64')]
1825         .ip: IPv6Address('2001:658:22a:cafe:200::1')
1826         .network: IPv6Address('2001:658:22a:cafe::')
1827         .hostmask: IPv6Address('::ffff:ffff:ffff:ffff')
1828         .broadcast: IPv6Address('2001:658:22a:cafe:ffff:ffff:ffff:ffff')
1829         .netmask: IPv6Address('ffff:ffff:ffff:ffff::')
1830         .prefixlen: 64
1831
1832     """
1833
1834     def __init__(self, address, strict=False):
1835         """Instantiate a new IPv6 Network object.
1836
1837         Args:
1838             address: A string or integer representing the IPv6 network or the IP
1839               and prefix/netmask.
1840               '2001:4860::/128'
1841               '2001:4860:0000:0000:0000:0000:0000:0000/128'
1842               '2001:4860::'
1843               are all functionally the same in IPv6.  That is to say,
1844               failing to provide a subnetmask will create an object with
1845               a mask of /128.
1846
1847               Additionally, an integer can be passed, so
1848               IPv6Network('2001:4860::') ==
1849                 IPv6Network(42541956101370907050197289607612071936L).
1850               or, more generally
1851               IPv6Network(IPv6Network('2001:4860::')._ip) ==
1852                 IPv6Network('2001:4860::')
1853
1854             strict: A boolean. If true, ensure that we have been passed
1855               A true network address, eg, 192.168.1.0/24 and not an
1856               IP address on a network, eg, 192.168.1.1/24.
1857
1858         Raises:
1859             AddressValueError: If address isn't a valid IPv6 address.
1860             NetmaskValueError: If the netmask isn't valid for
1861               an IPv6 address.
1862             ValueError: If strict was True and a network address was not
1863               supplied.
1864
1865         """
1866         _BaseNet.__init__(self, address)
1867         _BaseV6.__init__(self, address)
1868
1869         # Constructing from an integer or packed bytes.
1870         if isinstance(address, (int, Bytes)):
1871             self.ip = IPv6Address(address)
1872             self._ip = self.ip._ip
1873             self._prefixlen = self._max_prefixlen
1874             self.netmask = IPv6Address(self._ALL_ONES)
1875             return
1876
1877         # Assume input argument to be string or any object representation
1878         # which converts into a formatted IP prefix string.
1879         addr = str(address).split("/")
1880
1881         if len(addr) > 2:
1882             raise AddressValueError(address)
1883
1884         self._ip = self._ip_int_from_string(addr[0])
1885         self.ip = IPv6Address(self._ip)
1886
1887         if len(addr) == 2:
1888             # This may raise NetmaskValueError
1889             self._prefixlen = self._prefix_from_prefix_string(addr[1])
1890         else:
1891             self._prefixlen = self._max_prefixlen
1892
1893         self.netmask = IPv6Address(self._ip_int_from_prefix(self._prefixlen))
1894
1895         if strict:
1896             if self.ip != self.network:
1897                 raise ValueError("%s has host bits set" % self.ip)
1898         if self._prefixlen == (self._max_prefixlen - 1):
1899             self.iterhosts = self.__iter__
1900
1901     @property
1902     def with_netmask(self):
1903         return self.with_prefixlen