Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/ipaddress.py: 51%
891 statements
« prev ^ index » next coverage.py v7.0.5, created at 2023-01-17 06:13 +0000
1# Copyright 2007 Google Inc.
2# Licensed to PSF under a Contributor Agreement.
4"""A fast, lightweight IPv4/IPv6 manipulation library in Python.
6This library is used to create/poke/manipulate IPv4 and IPv6 addresses
7and networks.
9"""
11__version__ = '1.0'
14import functools
16IPV4LENGTH = 32
17IPV6LENGTH = 128
19class AddressValueError(ValueError):
20 """A Value Error related to the address."""
23class NetmaskValueError(ValueError):
24 """A Value Error related to the netmask."""
27def ip_address(address):
28 """Take an IP string/int and return an object of the correct type.
30 Args:
31 address: A string or integer, the IP address. Either IPv4 or
32 IPv6 addresses may be supplied; integers less than 2**32 will
33 be considered to be IPv4 by default.
35 Returns:
36 An IPv4Address or IPv6Address object.
38 Raises:
39 ValueError: if the *address* passed isn't either a v4 or a v6
40 address
42 """
43 try:
44 return IPv4Address(address)
45 except (AddressValueError, NetmaskValueError):
46 pass
48 try:
49 return IPv6Address(address)
50 except (AddressValueError, NetmaskValueError):
51 pass
53 raise ValueError('%r does not appear to be an IPv4 or IPv6 address' %
54 address)
57def ip_network(address, strict=True):
58 """Take an IP string/int and return an object of the correct type.
60 Args:
61 address: A string or integer, the IP network. Either IPv4 or
62 IPv6 networks may be supplied; integers less than 2**32 will
63 be considered to be IPv4 by default.
65 Returns:
66 An IPv4Network or IPv6Network object.
68 Raises:
69 ValueError: if the string passed isn't either a v4 or a v6
70 address. Or if the network has host bits set.
72 """
73 try:
74 return IPv4Network(address, strict)
75 except (AddressValueError, NetmaskValueError):
76 pass
78 try:
79 return IPv6Network(address, strict)
80 except (AddressValueError, NetmaskValueError):
81 pass
83 raise ValueError('%r does not appear to be an IPv4 or IPv6 network' %
84 address)
87def ip_interface(address):
88 """Take an IP string/int and return an object of the correct type.
90 Args:
91 address: A string or integer, the IP address. Either IPv4 or
92 IPv6 addresses may be supplied; integers less than 2**32 will
93 be considered to be IPv4 by default.
95 Returns:
96 An IPv4Interface or IPv6Interface object.
98 Raises:
99 ValueError: if the string passed isn't either a v4 or a v6
100 address.
102 Notes:
103 The IPv?Interface classes describe an Address on a particular
104 Network, so they're basically a combination of both the Address
105 and Network classes.
107 """
108 try:
109 return IPv4Interface(address)
110 except (AddressValueError, NetmaskValueError):
111 pass
113 try:
114 return IPv6Interface(address)
115 except (AddressValueError, NetmaskValueError):
116 pass
118 raise ValueError('%r does not appear to be an IPv4 or IPv6 interface' %
119 address)
122def v4_int_to_packed(address):
123 """Represent an address as 4 packed bytes in network (big-endian) order.
125 Args:
126 address: An integer representation of an IPv4 IP address.
128 Returns:
129 The integer address packed as 4 bytes in network (big-endian) order.
131 Raises:
132 ValueError: If the integer is negative or too large to be an
133 IPv4 IP address.
135 """
136 try:
137 return address.to_bytes(4, 'big')
138 except OverflowError:
139 raise ValueError("Address negative or too large for IPv4")
142def v6_int_to_packed(address):
143 """Represent an address as 16 packed bytes in network (big-endian) order.
145 Args:
146 address: An integer representation of an IPv6 IP address.
148 Returns:
149 The integer address packed as 16 bytes in network (big-endian) order.
151 """
152 try:
153 return address.to_bytes(16, 'big')
154 except OverflowError:
155 raise ValueError("Address negative or too large for IPv6")
158def _split_optional_netmask(address):
159 """Helper to split the netmask and raise AddressValueError if needed"""
160 addr = str(address).split('/')
161 if len(addr) > 2:
162 raise AddressValueError("Only one '/' permitted in %r" % address)
163 return addr
166def _find_address_range(addresses):
167 """Find a sequence of sorted deduplicated IPv#Address.
169 Args:
170 addresses: a list of IPv#Address objects.
172 Yields:
173 A tuple containing the first and last IP addresses in the sequence.
175 """
176 it = iter(addresses)
177 first = last = next(it)
178 for ip in it:
179 if ip._ip != last._ip + 1:
180 yield first, last
181 first = ip
182 last = ip
183 yield first, last
186def _count_righthand_zero_bits(number, bits):
187 """Count the number of zero bits on the right hand side.
189 Args:
190 number: an integer.
191 bits: maximum number of bits to count.
193 Returns:
194 The number of zero bits on the right hand side of the number.
196 """
197 if number == 0:
198 return bits
199 return min(bits, (~number & (number-1)).bit_length())
202def summarize_address_range(first, last):
203 """Summarize a network range given the first and last IP addresses.
205 Example:
206 >>> list(summarize_address_range(IPv4Address('192.0.2.0'),
207 ... IPv4Address('192.0.2.130')))
208 ... #doctest: +NORMALIZE_WHITESPACE
209 [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'),
210 IPv4Network('192.0.2.130/32')]
212 Args:
213 first: the first IPv4Address or IPv6Address in the range.
214 last: the last IPv4Address or IPv6Address in the range.
216 Returns:
217 An iterator of the summarized IPv(4|6) network objects.
219 Raise:
220 TypeError:
221 If the first and last objects are not IP addresses.
222 If the first and last objects are not the same version.
223 ValueError:
224 If the last object is not greater than the first.
225 If the version of the first address is not 4 or 6.
227 """
228 if (not (isinstance(first, _BaseAddress) and
229 isinstance(last, _BaseAddress))):
230 raise TypeError('first and last must be IP addresses, not networks')
231 if first.version != last.version:
232 raise TypeError("%s and %s are not of the same version" % (
233 first, last))
234 if first > last:
235 raise ValueError('last IP address must be greater than first')
237 if first.version == 4:
238 ip = IPv4Network
239 elif first.version == 6:
240 ip = IPv6Network
241 else:
242 raise ValueError('unknown IP version')
244 ip_bits = first._max_prefixlen
245 first_int = first._ip
246 last_int = last._ip
247 while first_int <= last_int:
248 nbits = min(_count_righthand_zero_bits(first_int, ip_bits),
249 (last_int - first_int + 1).bit_length() - 1)
250 net = ip((first_int, ip_bits - nbits))
251 yield net
252 first_int += 1 << nbits
253 if first_int - 1 == ip._ALL_ONES:
254 break
257def _collapse_addresses_internal(addresses):
258 """Loops through the addresses, collapsing concurrent netblocks.
260 Example:
262 ip1 = IPv4Network('192.0.2.0/26')
263 ip2 = IPv4Network('192.0.2.64/26')
264 ip3 = IPv4Network('192.0.2.128/26')
265 ip4 = IPv4Network('192.0.2.192/26')
267 _collapse_addresses_internal([ip1, ip2, ip3, ip4]) ->
268 [IPv4Network('192.0.2.0/24')]
270 This shouldn't be called directly; it is called via
271 collapse_addresses([]).
273 Args:
274 addresses: A list of IPv4Network's or IPv6Network's
276 Returns:
277 A list of IPv4Network's or IPv6Network's depending on what we were
278 passed.
280 """
281 # First merge
282 to_merge = list(addresses)
283 subnets = {}
284 while to_merge:
285 net = to_merge.pop()
286 supernet = net.supernet()
287 existing = subnets.get(supernet)
288 if existing is None:
289 subnets[supernet] = net
290 elif existing != net:
291 # Merge consecutive subnets
292 del subnets[supernet]
293 to_merge.append(supernet)
294 # Then iterate over resulting networks, skipping subsumed subnets
295 last = None
296 for net in sorted(subnets.values()):
297 if last is not None:
298 # Since they are sorted, last.network_address <= net.network_address
299 # is a given.
300 if last.broadcast_address >= net.broadcast_address:
301 continue
302 yield net
303 last = net
306def collapse_addresses(addresses):
307 """Collapse a list of IP objects.
309 Example:
310 collapse_addresses([IPv4Network('192.0.2.0/25'),
311 IPv4Network('192.0.2.128/25')]) ->
312 [IPv4Network('192.0.2.0/24')]
314 Args:
315 addresses: An iterator of IPv4Network or IPv6Network objects.
317 Returns:
318 An iterator of the collapsed IPv(4|6)Network objects.
320 Raises:
321 TypeError: If passed a list of mixed version objects.
323 """
324 addrs = []
325 ips = []
326 nets = []
328 # split IP addresses and networks
329 for ip in addresses:
330 if isinstance(ip, _BaseAddress):
331 if ips and ips[-1]._version != ip._version:
332 raise TypeError("%s and %s are not of the same version" % (
333 ip, ips[-1]))
334 ips.append(ip)
335 elif ip._prefixlen == ip._max_prefixlen:
336 if ips and ips[-1]._version != ip._version:
337 raise TypeError("%s and %s are not of the same version" % (
338 ip, ips[-1]))
339 try:
340 ips.append(ip.ip)
341 except AttributeError:
342 ips.append(ip.network_address)
343 else:
344 if nets and nets[-1]._version != ip._version:
345 raise TypeError("%s and %s are not of the same version" % (
346 ip, nets[-1]))
347 nets.append(ip)
349 # sort and dedup
350 ips = sorted(set(ips))
352 # find consecutive address ranges in the sorted sequence and summarize them
353 if ips:
354 for first, last in _find_address_range(ips):
355 addrs.extend(summarize_address_range(first, last))
357 return _collapse_addresses_internal(addrs + nets)
360def get_mixed_type_key(obj):
361 """Return a key suitable for sorting between networks and addresses.
363 Address and Network objects are not sortable by default; they're
364 fundamentally different so the expression
366 IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')
368 doesn't make any sense. There are some times however, where you may wish
369 to have ipaddress sort these for you anyway. If you need to do this, you
370 can use this function as the key= argument to sorted().
372 Args:
373 obj: either a Network or Address object.
374 Returns:
375 appropriate key.
377 """
378 if isinstance(obj, _BaseNetwork):
379 return obj._get_networks_key()
380 elif isinstance(obj, _BaseAddress):
381 return obj._get_address_key()
382 return NotImplemented
385class _IPAddressBase:
387 """The mother class."""
389 __slots__ = ()
391 @property
392 def exploded(self):
393 """Return the longhand version of the IP address as a string."""
394 return self._explode_shorthand_ip_string()
396 @property
397 def compressed(self):
398 """Return the shorthand version of the IP address as a string."""
399 return str(self)
401 @property
402 def reverse_pointer(self):
403 """The name of the reverse DNS pointer for the IP address, e.g.:
404 >>> ipaddress.ip_address("127.0.0.1").reverse_pointer
405 '1.0.0.127.in-addr.arpa'
406 >>> ipaddress.ip_address("2001:db8::1").reverse_pointer
407 '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'
409 """
410 return self._reverse_pointer()
412 @property
413 def version(self):
414 msg = '%200s has no version specified' % (type(self),)
415 raise NotImplementedError(msg)
417 def _check_int_address(self, address):
418 if address < 0:
419 msg = "%d (< 0) is not permitted as an IPv%d address"
420 raise AddressValueError(msg % (address, self._version))
421 if address > self._ALL_ONES:
422 msg = "%d (>= 2**%d) is not permitted as an IPv%d address"
423 raise AddressValueError(msg % (address, self._max_prefixlen,
424 self._version))
426 def _check_packed_address(self, address, expected_len):
427 address_len = len(address)
428 if address_len != expected_len:
429 msg = "%r (len %d != %d) is not permitted as an IPv%d address"
430 raise AddressValueError(msg % (address, address_len,
431 expected_len, self._version))
433 @classmethod
434 def _ip_int_from_prefix(cls, prefixlen):
435 """Turn the prefix length into a bitwise netmask
437 Args:
438 prefixlen: An integer, the prefix length.
440 Returns:
441 An integer.
443 """
444 return cls._ALL_ONES ^ (cls._ALL_ONES >> prefixlen)
446 @classmethod
447 def _prefix_from_ip_int(cls, ip_int):
448 """Return prefix length from the bitwise netmask.
450 Args:
451 ip_int: An integer, the netmask in expanded bitwise format
453 Returns:
454 An integer, the prefix length.
456 Raises:
457 ValueError: If the input intermingles zeroes & ones
458 """
459 trailing_zeroes = _count_righthand_zero_bits(ip_int,
460 cls._max_prefixlen)
461 prefixlen = cls._max_prefixlen - trailing_zeroes
462 leading_ones = ip_int >> trailing_zeroes
463 all_ones = (1 << prefixlen) - 1
464 if leading_ones != all_ones:
465 byteslen = cls._max_prefixlen // 8
466 details = ip_int.to_bytes(byteslen, 'big')
467 msg = 'Netmask pattern %r mixes zeroes & ones'
468 raise ValueError(msg % details)
469 return prefixlen
471 @classmethod
472 def _report_invalid_netmask(cls, netmask_str):
473 msg = '%r is not a valid netmask' % netmask_str
474 raise NetmaskValueError(msg) from None
476 @classmethod
477 def _prefix_from_prefix_string(cls, prefixlen_str):
478 """Return prefix length from a numeric string
480 Args:
481 prefixlen_str: The string to be converted
483 Returns:
484 An integer, the prefix length.
486 Raises:
487 NetmaskValueError: If the input is not a valid netmask
488 """
489 # int allows a leading +/- as well as surrounding whitespace,
490 # 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 try:
494 prefixlen = int(prefixlen_str)
495 except ValueError:
496 cls._report_invalid_netmask(prefixlen_str)
497 if not (0 <= prefixlen <= cls._max_prefixlen):
498 cls._report_invalid_netmask(prefixlen_str)
499 return prefixlen
501 @classmethod
502 def _prefix_from_ip_string(cls, ip_str):
503 """Turn a netmask/hostmask string into a prefix length
505 Args:
506 ip_str: The netmask/hostmask to be converted
508 Returns:
509 An integer, the prefix length.
511 Raises:
512 NetmaskValueError: If the input is not a valid netmask/hostmask
513 """
514 # Parse the netmask/hostmask like an IP address.
515 try:
516 ip_int = cls._ip_int_from_string(ip_str)
517 except AddressValueError:
518 cls._report_invalid_netmask(ip_str)
520 # Try matching a netmask (this would be /1*0*/ as a bitwise regexp).
521 # Note that the two ambiguous cases (all-ones and all-zeroes) are
522 # treated as netmasks.
523 try:
524 return cls._prefix_from_ip_int(ip_int)
525 except ValueError:
526 pass
528 # 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)
535 @classmethod
536 def _split_addr_prefix(cls, address):
537 """Helper function to parse address of Network/Interface.
539 Arg:
540 address: Argument of Network/Interface.
542 Returns:
543 (addr, prefix) tuple.
544 """
545 # a packed address or integer
546 if isinstance(address, (bytes, int)):
547 return address, cls._max_prefixlen
549 if not isinstance(address, tuple):
550 # Assume input argument to be string or any object representation
551 # which converts into a formatted IP prefix string.
552 address = _split_optional_netmask(address)
554 # Constructing from a tuple (addr, [mask])
555 if len(address) > 1:
556 return address
557 return address[0], cls._max_prefixlen
559 def __reduce__(self):
560 return self.__class__, (str(self),)
563@functools.total_ordering
564class _BaseAddress(_IPAddressBase):
566 """A generic IP object.
568 This IP class contains the version independent methods which are
569 used by single IP addresses.
570 """
572 __slots__ = ()
574 def __int__(self):
575 return self._ip
577 def __eq__(self, other):
578 try:
579 return (self._ip == other._ip
580 and self._version == other._version)
581 except AttributeError:
582 return NotImplemented
584 def __lt__(self, other):
585 if not isinstance(other, _BaseAddress):
586 return NotImplemented
587 if self._version != other._version:
588 raise TypeError('%s and %s are not of the same version' % (
589 self, other))
590 if self._ip != other._ip:
591 return self._ip < other._ip
592 return False
594 # Shorthand for Integer addition and subtraction. This is not
595 # meant to ever support addition/subtraction of addresses.
596 def __add__(self, other):
597 if not isinstance(other, int):
598 return NotImplemented
599 return self.__class__(int(self) + other)
601 def __sub__(self, other):
602 if not isinstance(other, int):
603 return NotImplemented
604 return self.__class__(int(self) - other)
606 def __repr__(self):
607 return '%s(%r)' % (self.__class__.__name__, str(self))
609 def __str__(self):
610 return str(self._string_from_ip_int(self._ip))
612 def __hash__(self):
613 return hash(hex(int(self._ip)))
615 def _get_address_key(self):
616 return (self._version, self)
618 def __reduce__(self):
619 return self.__class__, (self._ip,)
622@functools.total_ordering
623class _BaseNetwork(_IPAddressBase):
624 """A generic IP network object.
626 This IP class contains the version independent methods which are
627 used by networks.
628 """
630 def __repr__(self):
631 return '%s(%r)' % (self.__class__.__name__, str(self))
633 def __str__(self):
634 return '%s/%d' % (self.network_address, self.prefixlen)
636 def hosts(self):
637 """Generate Iterator over usable hosts in a network.
639 This is like __iter__ except it doesn't return the network
640 or broadcast addresses.
642 """
643 network = int(self.network_address)
644 broadcast = int(self.broadcast_address)
645 for x in range(network + 1, broadcast):
646 yield self._address_class(x)
648 def __iter__(self):
649 network = int(self.network_address)
650 broadcast = int(self.broadcast_address)
651 for x in range(network, broadcast + 1):
652 yield self._address_class(x)
654 def __getitem__(self, n):
655 network = int(self.network_address)
656 broadcast = int(self.broadcast_address)
657 if n >= 0:
658 if network + n > broadcast:
659 raise IndexError('address out of range')
660 return self._address_class(network + n)
661 else:
662 n += 1
663 if broadcast + n < network:
664 raise IndexError('address out of range')
665 return self._address_class(broadcast + n)
667 def __lt__(self, other):
668 if not isinstance(other, _BaseNetwork):
669 return NotImplemented
670 if self._version != other._version:
671 raise TypeError('%s and %s are not of the same version' % (
672 self, other))
673 if self.network_address != other.network_address:
674 return self.network_address < other.network_address
675 if self.netmask != other.netmask:
676 return self.netmask < other.netmask
677 return False
679 def __eq__(self, other):
680 try:
681 return (self._version == other._version and
682 self.network_address == other.network_address and
683 int(self.netmask) == int(other.netmask))
684 except AttributeError:
685 return NotImplemented
687 def __hash__(self):
688 return hash(int(self.network_address) ^ int(self.netmask))
690 def __contains__(self, other):
691 # always false if one is v4 and the other is v6.
692 if self._version != other._version:
693 return False
694 # dealing with another network.
695 if isinstance(other, _BaseNetwork):
696 return False
697 # dealing with another address
698 else:
699 # address
700 return other._ip & self.netmask._ip == self.network_address._ip
702 def overlaps(self, other):
703 """Tell if self is partly contained in other."""
704 return self.network_address in other or (
705 self.broadcast_address in other or (
706 other.network_address in self or (
707 other.broadcast_address in self)))
709 @functools.cached_property
710 def broadcast_address(self):
711 return self._address_class(int(self.network_address) |
712 int(self.hostmask))
714 @functools.cached_property
715 def hostmask(self):
716 return self._address_class(int(self.netmask) ^ self._ALL_ONES)
718 @property
719 def with_prefixlen(self):
720 return '%s/%d' % (self.network_address, self._prefixlen)
722 @property
723 def with_netmask(self):
724 return '%s/%s' % (self.network_address, self.netmask)
726 @property
727 def with_hostmask(self):
728 return '%s/%s' % (self.network_address, self.hostmask)
730 @property
731 def num_addresses(self):
732 """Number of hosts in the current subnet."""
733 return int(self.broadcast_address) - int(self.network_address) + 1
735 @property
736 def _address_class(self):
737 # Returning bare address objects (rather than interfaces) allows for
738 # more consistent behaviour across the network address, broadcast
739 # address and individual host addresses.
740 msg = '%200s has no associated address class' % (type(self),)
741 raise NotImplementedError(msg)
743 @property
744 def prefixlen(self):
745 return self._prefixlen
747 def address_exclude(self, other):
748 """Remove an address from a larger block.
750 For example:
752 addr1 = ip_network('192.0.2.0/28')
753 addr2 = ip_network('192.0.2.1/32')
754 list(addr1.address_exclude(addr2)) =
755 [IPv4Network('192.0.2.0/32'), IPv4Network('192.0.2.2/31'),
756 IPv4Network('192.0.2.4/30'), IPv4Network('192.0.2.8/29')]
758 or IPv6:
760 addr1 = ip_network('2001:db8::1/32')
761 addr2 = ip_network('2001:db8::1/128')
762 list(addr1.address_exclude(addr2)) =
763 [ip_network('2001:db8::1/128'),
764 ip_network('2001:db8::2/127'),
765 ip_network('2001:db8::4/126'),
766 ip_network('2001:db8::8/125'),
767 ...
768 ip_network('2001:db8:8000::/33')]
770 Args:
771 other: An IPv4Network or IPv6Network object of the same type.
773 Returns:
774 An iterator of the IPv(4|6)Network objects which is self
775 minus other.
777 Raises:
778 TypeError: If self and other are of differing address
779 versions, or if other is not a network object.
780 ValueError: If other is not completely contained by self.
782 """
783 if not self._version == other._version:
784 raise TypeError("%s and %s are not of the same version" % (
785 self, other))
787 if not isinstance(other, _BaseNetwork):
788 raise TypeError("%s is not a network object" % other)
790 if not other.subnet_of(self):
791 raise ValueError('%s not contained in %s' % (other, self))
792 if other == self:
793 return
795 # Make sure we're comparing the network of other.
796 other = other.__class__('%s/%s' % (other.network_address,
797 other.prefixlen))
799 s1, s2 = self.subnets()
800 while s1 != other and s2 != other:
801 if other.subnet_of(s1):
802 yield s2
803 s1, s2 = s1.subnets()
804 elif other.subnet_of(s2):
805 yield s1
806 s1, s2 = s2.subnets()
807 else:
808 # If we got here, there's a bug somewhere.
809 raise AssertionError('Error performing exclusion: '
810 's1: %s s2: %s other: %s' %
811 (s1, s2, other))
812 if s1 == other:
813 yield s2
814 elif s2 == other:
815 yield s1
816 else:
817 # If we got here, there's a bug somewhere.
818 raise AssertionError('Error performing exclusion: '
819 's1: %s s2: %s other: %s' %
820 (s1, s2, other))
822 def compare_networks(self, other):
823 """Compare two IP objects.
825 This is only concerned about the comparison of the integer
826 representation of the network addresses. This means that the
827 host bits aren't considered at all in this method. If you want
828 to compare host bits, you can easily enough do a
829 'HostA._ip < HostB._ip'
831 Args:
832 other: An IP object.
834 Returns:
835 If the IP versions of self and other are the same, returns:
837 -1 if self < other:
838 eg: IPv4Network('192.0.2.0/25') < IPv4Network('192.0.2.128/25')
839 IPv6Network('2001:db8::1000/124') <
840 IPv6Network('2001:db8::2000/124')
841 0 if self == other
842 eg: IPv4Network('192.0.2.0/24') == IPv4Network('192.0.2.0/24')
843 IPv6Network('2001:db8::1000/124') ==
844 IPv6Network('2001:db8::1000/124')
845 1 if self > other
846 eg: IPv4Network('192.0.2.128/25') > IPv4Network('192.0.2.0/25')
847 IPv6Network('2001:db8::2000/124') >
848 IPv6Network('2001:db8::1000/124')
850 Raises:
851 TypeError if the IP versions are different.
853 """
854 # does this need to raise a ValueError?
855 if self._version != other._version:
856 raise TypeError('%s and %s are not of the same type' % (
857 self, other))
858 # self._version == other._version below here:
859 if self.network_address < other.network_address:
860 return -1
861 if self.network_address > other.network_address:
862 return 1
863 # self.network_address == other.network_address below here:
864 if self.netmask < other.netmask:
865 return -1
866 if self.netmask > other.netmask:
867 return 1
868 return 0
870 def _get_networks_key(self):
871 """Network-only key function.
873 Returns an object that identifies this address' network and
874 netmask. This function is a suitable "key" argument for sorted()
875 and list.sort().
877 """
878 return (self._version, self.network_address, self.netmask)
880 def subnets(self, prefixlen_diff=1, new_prefix=None):
881 """The subnets which join to make the current subnet.
883 In the case that self contains only one IP
884 (self._prefixlen == 32 for IPv4 or self._prefixlen == 128
885 for IPv6), yield an iterator with just ourself.
887 Args:
888 prefixlen_diff: An integer, the amount the prefix length
889 should be increased by. This should not be set if
890 new_prefix is also set.
891 new_prefix: The desired new prefix length. This must be a
892 larger number (smaller prefix) than the existing prefix.
893 This should not be set if prefixlen_diff is also set.
895 Returns:
896 An iterator of IPv(4|6) objects.
898 Raises:
899 ValueError: The prefixlen_diff is too small or too large.
900 OR
901 prefixlen_diff and new_prefix are both set or new_prefix
902 is a smaller number than the current prefix (smaller
903 number means a larger network)
905 """
906 if self._prefixlen == self._max_prefixlen:
907 yield self
908 return
910 if new_prefix is not None:
911 if new_prefix < self._prefixlen:
912 raise ValueError('new prefix must be longer')
913 if prefixlen_diff != 1:
914 raise ValueError('cannot set prefixlen_diff and new_prefix')
915 prefixlen_diff = new_prefix - self._prefixlen
917 if prefixlen_diff < 0:
918 raise ValueError('prefix length diff must be > 0')
919 new_prefixlen = self._prefixlen + prefixlen_diff
921 if new_prefixlen > self._max_prefixlen:
922 raise ValueError(
923 'prefix length diff %d is invalid for netblock %s' % (
924 new_prefixlen, self))
926 start = int(self.network_address)
927 end = int(self.broadcast_address) + 1
928 step = (int(self.hostmask) + 1) >> prefixlen_diff
929 for new_addr in range(start, end, step):
930 current = self.__class__((new_addr, new_prefixlen))
931 yield current
933 def supernet(self, prefixlen_diff=1, new_prefix=None):
934 """The supernet containing the current network.
936 Args:
937 prefixlen_diff: An integer, the amount the prefix length of
938 the network should be decreased by. For example, given a
939 /24 network and a prefixlen_diff of 3, a supernet with a
940 /21 netmask is returned.
942 Returns:
943 An IPv4 network object.
945 Raises:
946 ValueError: If self.prefixlen - prefixlen_diff < 0. I.e., you have
947 a negative prefix length.
948 OR
949 If prefixlen_diff and new_prefix are both set or new_prefix is a
950 larger number than the current prefix (larger number means a
951 smaller network)
953 """
954 if self._prefixlen == 0:
955 return self
957 if new_prefix is not None:
958 if new_prefix > self._prefixlen:
959 raise ValueError('new prefix must be shorter')
960 if prefixlen_diff != 1:
961 raise ValueError('cannot set prefixlen_diff and new_prefix')
962 prefixlen_diff = self._prefixlen - new_prefix
964 new_prefixlen = self.prefixlen - prefixlen_diff
965 if new_prefixlen < 0:
966 raise ValueError(
967 'current prefixlen is %d, cannot have a prefixlen_diff of %d' %
968 (self.prefixlen, prefixlen_diff))
969 return self.__class__((
970 int(self.network_address) & (int(self.netmask) << prefixlen_diff),
971 new_prefixlen
972 ))
974 @property
975 def is_multicast(self):
976 """Test if the address is reserved for multicast use.
978 Returns:
979 A boolean, True if the address is a multicast address.
980 See RFC 2373 2.7 for details.
982 """
983 return (self.network_address.is_multicast and
984 self.broadcast_address.is_multicast)
986 @staticmethod
987 def _is_subnet_of(a, b):
988 try:
989 # Always false if one is v4 and the other is v6.
990 if a._version != b._version:
991 raise TypeError(f"{a} and {b} are not of the same version")
992 return (b.network_address <= a.network_address and
993 b.broadcast_address >= a.broadcast_address)
994 except AttributeError:
995 raise TypeError(f"Unable to test subnet containment "
996 f"between {a} and {b}")
998 def subnet_of(self, other):
999 """Return True if this network is a subnet of other."""
1000 return self._is_subnet_of(self, other)
1002 def supernet_of(self, other):
1003 """Return True if this network is a supernet of other."""
1004 return self._is_subnet_of(other, self)
1006 @property
1007 def is_reserved(self):
1008 """Test if the address is otherwise IETF reserved.
1010 Returns:
1011 A boolean, True if the address is within one of the
1012 reserved IPv6 Network ranges.
1014 """
1015 return (self.network_address.is_reserved and
1016 self.broadcast_address.is_reserved)
1018 @property
1019 def is_link_local(self):
1020 """Test if the address is reserved for link-local.
1022 Returns:
1023 A boolean, True if the address is reserved per RFC 4291.
1025 """
1026 return (self.network_address.is_link_local and
1027 self.broadcast_address.is_link_local)
1029 @property
1030 def is_private(self):
1031 """Test if this address is allocated for private networks.
1033 Returns:
1034 A boolean, True if the address is reserved per
1035 iana-ipv4-special-registry or iana-ipv6-special-registry.
1037 """
1038 return (self.network_address.is_private and
1039 self.broadcast_address.is_private)
1041 @property
1042 def is_global(self):
1043 """Test if this address is allocated for public networks.
1045 Returns:
1046 A boolean, True if the address is not reserved per
1047 iana-ipv4-special-registry or iana-ipv6-special-registry.
1049 """
1050 return not self.is_private
1052 @property
1053 def is_unspecified(self):
1054 """Test if the address is unspecified.
1056 Returns:
1057 A boolean, True if this is the unspecified address as defined in
1058 RFC 2373 2.5.2.
1060 """
1061 return (self.network_address.is_unspecified and
1062 self.broadcast_address.is_unspecified)
1064 @property
1065 def is_loopback(self):
1066 """Test if the address is a loopback address.
1068 Returns:
1069 A boolean, True if the address is a loopback address as defined in
1070 RFC 2373 2.5.3.
1072 """
1073 return (self.network_address.is_loopback and
1074 self.broadcast_address.is_loopback)
1077class _BaseV4:
1079 """Base IPv4 object.
1081 The following methods are used by IPv4 objects in both single IP
1082 addresses and networks.
1084 """
1086 __slots__ = ()
1087 _version = 4
1088 # Equivalent to 255.255.255.255 or 32 bits of 1's.
1089 _ALL_ONES = (2**IPV4LENGTH) - 1
1091 _max_prefixlen = IPV4LENGTH
1092 # There are only a handful of valid v4 netmasks, so we cache them all
1093 # when constructed (see _make_netmask()).
1094 _netmask_cache = {}
1096 def _explode_shorthand_ip_string(self):
1097 return str(self)
1099 @classmethod
1100 def _make_netmask(cls, arg):
1101 """Make a (netmask, prefix_len) tuple from the given argument.
1103 Argument can be:
1104 - an integer (the prefix length)
1105 - a string representing the prefix length (e.g. "24")
1106 - a string representing the prefix netmask (e.g. "255.255.255.0")
1107 """
1108 if arg not in cls._netmask_cache:
1109 if isinstance(arg, int):
1110 prefixlen = arg
1111 if not (0 <= prefixlen <= cls._max_prefixlen):
1112 cls._report_invalid_netmask(prefixlen)
1113 else:
1114 try:
1115 # Check for a netmask in prefix length form
1116 prefixlen = cls._prefix_from_prefix_string(arg)
1117 except NetmaskValueError:
1118 # Check for a netmask or hostmask in dotted-quad form.
1119 # This may raise NetmaskValueError.
1120 prefixlen = cls._prefix_from_ip_string(arg)
1121 netmask = IPv4Address(cls._ip_int_from_prefix(prefixlen))
1122 cls._netmask_cache[arg] = netmask, prefixlen
1123 return cls._netmask_cache[arg]
1125 @classmethod
1126 def _ip_int_from_string(cls, ip_str):
1127 """Turn the given IP string into an integer for comparison.
1129 Args:
1130 ip_str: A string, the IP ip_str.
1132 Returns:
1133 The IP ip_str as an integer.
1135 Raises:
1136 AddressValueError: if ip_str isn't a valid IPv4 Address.
1138 """
1139 if not ip_str:
1140 raise AddressValueError('Address cannot be empty')
1142 octets = ip_str.split('.')
1143 if len(octets) != 4:
1144 raise AddressValueError("Expected 4 octets in %r" % ip_str)
1146 try:
1147 return int.from_bytes(map(cls._parse_octet, octets), 'big')
1148 except ValueError as exc:
1149 raise AddressValueError("%s in %r" % (exc, ip_str)) from None
1151 @classmethod
1152 def _parse_octet(cls, octet_str):
1153 """Convert a decimal octet into an integer.
1155 Args:
1156 octet_str: A string, the number to parse.
1158 Returns:
1159 The octet as an integer.
1161 Raises:
1162 ValueError: if the octet isn't strictly a decimal from [0..255].
1164 """
1165 if not octet_str:
1166 raise ValueError("Empty octet not permitted")
1167 # Whitelist the characters, since int() allows a lot of bizarre stuff.
1168 if not (octet_str.isascii() and octet_str.isdigit()):
1169 msg = "Only decimal digits permitted in %r"
1170 raise ValueError(msg % octet_str)
1171 # We do the length check second, since the invalid character error
1172 # is likely to be more informative for the user
1173 if len(octet_str) > 3:
1174 msg = "At most 3 characters permitted in %r"
1175 raise ValueError(msg % octet_str)
1176 # Convert to integer (we know digits are legal)
1177 octet_int = int(octet_str, 10)
1178 if octet_int > 255:
1179 raise ValueError("Octet %d (> 255) not permitted" % octet_int)
1180 return octet_int
1182 @classmethod
1183 def _string_from_ip_int(cls, ip_int):
1184 """Turns a 32-bit integer into dotted decimal notation.
1186 Args:
1187 ip_int: An integer, the IP address.
1189 Returns:
1190 The IP address as a string in dotted decimal notation.
1192 """
1193 return '.'.join(map(str, ip_int.to_bytes(4, 'big')))
1195 def _reverse_pointer(self):
1196 """Return the reverse DNS pointer name for the IPv4 address.
1198 This implements the method described in RFC1035 3.5.
1200 """
1201 reverse_octets = str(self).split('.')[::-1]
1202 return '.'.join(reverse_octets) + '.in-addr.arpa'
1204 @property
1205 def max_prefixlen(self):
1206 return self._max_prefixlen
1208 @property
1209 def version(self):
1210 return self._version
1213class IPv4Address(_BaseV4, _BaseAddress):
1215 """Represent and manipulate single IPv4 Addresses."""
1217 __slots__ = ('_ip', '__weakref__')
1219 def __init__(self, address):
1221 """
1222 Args:
1223 address: A string or integer representing the IP
1225 Additionally, an integer can be passed, so
1226 IPv4Address('192.0.2.1') == IPv4Address(3221225985).
1227 or, more generally
1228 IPv4Address(int(IPv4Address('192.0.2.1'))) ==
1229 IPv4Address('192.0.2.1')
1231 Raises:
1232 AddressValueError: If ipaddress isn't a valid IPv4 address.
1234 """
1235 # Efficient constructor from integer.
1236 if isinstance(address, int):
1237 self._check_int_address(address)
1238 self._ip = address
1239 return
1241 # Constructing from a packed address
1242 if isinstance(address, bytes):
1243 self._check_packed_address(address, 4)
1244 self._ip = int.from_bytes(address, 'big')
1245 return
1247 # Assume input argument to be string or any object representation
1248 # which converts into a formatted IP string.
1249 addr_str = str(address)
1250 if '/' in addr_str:
1251 raise AddressValueError("Unexpected '/' in %r" % address)
1252 self._ip = self._ip_int_from_string(addr_str)
1254 @property
1255 def packed(self):
1256 """The binary representation of this address."""
1257 return v4_int_to_packed(self._ip)
1259 @property
1260 def is_reserved(self):
1261 """Test if the address is otherwise IETF reserved.
1263 Returns:
1264 A boolean, True if the address is within the
1265 reserved IPv4 Network range.
1267 """
1268 return self in self._constants._reserved_network
1270 @property
1271 @functools.lru_cache()
1272 def is_private(self):
1273 """Test if this address is allocated for private networks.
1275 Returns:
1276 A boolean, True if the address is reserved per
1277 iana-ipv4-special-registry.
1279 """
1280 return any(self in net for net in self._constants._private_networks)
1282 @property
1283 @functools.lru_cache()
1284 def is_global(self):
1285 return self not in self._constants._public_network and not self.is_private
1287 @property
1288 def is_multicast(self):
1289 """Test if the address is reserved for multicast use.
1291 Returns:
1292 A boolean, True if the address is multicast.
1293 See RFC 3171 for details.
1295 """
1296 return self in self._constants._multicast_network
1298 @property
1299 def is_unspecified(self):
1300 """Test if the address is unspecified.
1302 Returns:
1303 A boolean, True if this is the unspecified address as defined in
1304 RFC 5735 3.
1306 """
1307 return self == self._constants._unspecified_address
1309 @property
1310 def is_loopback(self):
1311 """Test if the address is a loopback address.
1313 Returns:
1314 A boolean, True if the address is a loopback per RFC 3330.
1316 """
1317 return self in self._constants._loopback_network
1319 @property
1320 def is_link_local(self):
1321 """Test if the address is reserved for link-local.
1323 Returns:
1324 A boolean, True if the address is link-local per RFC 3927.
1326 """
1327 return self in self._constants._linklocal_network
1330class IPv4Interface(IPv4Address):
1332 def __init__(self, address):
1333 addr, mask = self._split_addr_prefix(address)
1335 IPv4Address.__init__(self, addr)
1336 self.network = IPv4Network((addr, mask), strict=False)
1337 self.netmask = self.network.netmask
1338 self._prefixlen = self.network._prefixlen
1340 @functools.cached_property
1341 def hostmask(self):
1342 return self.network.hostmask
1344 def __str__(self):
1345 return '%s/%d' % (self._string_from_ip_int(self._ip),
1346 self._prefixlen)
1348 def __eq__(self, other):
1349 address_equal = IPv4Address.__eq__(self, other)
1350 if not address_equal or address_equal is NotImplemented:
1351 return address_equal
1352 try:
1353 return self.network == other.network
1354 except AttributeError:
1355 # An interface with an associated network is NOT the
1356 # same as an unassociated address. That's why the hash
1357 # takes the extra info into account.
1358 return False
1360 def __lt__(self, other):
1361 address_less = IPv4Address.__lt__(self, other)
1362 if address_less is NotImplemented:
1363 return NotImplemented
1364 try:
1365 return (self.network < other.network or
1366 self.network == other.network and address_less)
1367 except AttributeError:
1368 # We *do* allow addresses and interfaces to be sorted. The
1369 # unassociated address is considered less than all interfaces.
1370 return False
1372 def __hash__(self):
1373 return self._ip ^ self._prefixlen ^ int(self.network.network_address)
1375 __reduce__ = _IPAddressBase.__reduce__
1377 @property
1378 def ip(self):
1379 return IPv4Address(self._ip)
1381 @property
1382 def with_prefixlen(self):
1383 return '%s/%s' % (self._string_from_ip_int(self._ip),
1384 self._prefixlen)
1386 @property
1387 def with_netmask(self):
1388 return '%s/%s' % (self._string_from_ip_int(self._ip),
1389 self.netmask)
1391 @property
1392 def with_hostmask(self):
1393 return '%s/%s' % (self._string_from_ip_int(self._ip),
1394 self.hostmask)
1397class IPv4Network(_BaseV4, _BaseNetwork):
1399 """This class represents and manipulates 32-bit IPv4 network + addresses..
1401 Attributes: [examples for IPv4Network('192.0.2.0/27')]
1402 .network_address: IPv4Address('192.0.2.0')
1403 .hostmask: IPv4Address('0.0.0.31')
1404 .broadcast_address: IPv4Address('192.0.2.32')
1405 .netmask: IPv4Address('255.255.255.224')
1406 .prefixlen: 27
1408 """
1409 # Class to use when creating address objects
1410 _address_class = IPv4Address
1412 def __init__(self, address, strict=True):
1413 """Instantiate a new IPv4 network object.
1415 Args:
1416 address: A string or integer representing the IP [& network].
1417 '192.0.2.0/24'
1418 '192.0.2.0/255.255.255.0'
1419 '192.0.0.2/0.0.0.255'
1420 are all functionally the same in IPv4. Similarly,
1421 '192.0.2.1'
1422 '192.0.2.1/255.255.255.255'
1423 '192.0.2.1/32'
1424 are also functionally equivalent. That is to say, failing to
1425 provide a subnetmask will create an object with a mask of /32.
1427 If the mask (portion after the / in the argument) is given in
1428 dotted quad form, it is treated as a netmask if it starts with a
1429 non-zero field (e.g. /255.0.0.0 == /8) and as a hostmask if it
1430 starts with a zero field (e.g. 0.255.255.255 == /8), with the
1431 single exception of an all-zero mask which is treated as a
1432 netmask == /0. If no mask is given, a default of /32 is used.
1434 Additionally, an integer can be passed, so
1435 IPv4Network('192.0.2.1') == IPv4Network(3221225985)
1436 or, more generally
1437 IPv4Interface(int(IPv4Interface('192.0.2.1'))) ==
1438 IPv4Interface('192.0.2.1')
1440 Raises:
1441 AddressValueError: If ipaddress isn't a valid IPv4 address.
1442 NetmaskValueError: If the netmask isn't valid for
1443 an IPv4 address.
1444 ValueError: If strict is True and a network address is not
1445 supplied.
1446 """
1447 addr, mask = self._split_addr_prefix(address)
1449 self.network_address = IPv4Address(addr)
1450 self.netmask, self._prefixlen = self._make_netmask(mask)
1451 packed = int(self.network_address)
1452 if packed & int(self.netmask) != packed:
1453 if strict:
1454 raise ValueError('%s has host bits set' % self)
1455 else:
1456 self.network_address = IPv4Address(packed &
1457 int(self.netmask))
1459 if self._prefixlen == (self._max_prefixlen - 1):
1460 self.hosts = self.__iter__
1462 @property
1463 @functools.lru_cache()
1464 def is_global(self):
1465 """Test if this address is allocated for public networks.
1467 Returns:
1468 A boolean, True if the address is not reserved per
1469 iana-ipv4-special-registry.
1471 """
1472 return (not (self.network_address in IPv4Network('100.64.0.0/10') and
1473 self.broadcast_address in IPv4Network('100.64.0.0/10')) and
1474 not self.is_private)
1477class _IPv4Constants:
1478 _linklocal_network = IPv4Network('169.254.0.0/16')
1480 _loopback_network = IPv4Network('127.0.0.0/8')
1482 _multicast_network = IPv4Network('224.0.0.0/4')
1484 _public_network = IPv4Network('100.64.0.0/10')
1486 _private_networks = [
1487 IPv4Network('0.0.0.0/8'),
1488 IPv4Network('10.0.0.0/8'),
1489 IPv4Network('127.0.0.0/8'),
1490 IPv4Network('169.254.0.0/16'),
1491 IPv4Network('172.16.0.0/12'),
1492 IPv4Network('192.0.0.0/29'),
1493 IPv4Network('192.0.0.170/31'),
1494 IPv4Network('192.0.2.0/24'),
1495 IPv4Network('192.168.0.0/16'),
1496 IPv4Network('198.18.0.0/15'),
1497 IPv4Network('198.51.100.0/24'),
1498 IPv4Network('203.0.113.0/24'),
1499 IPv4Network('240.0.0.0/4'),
1500 IPv4Network('255.255.255.255/32'),
1501 ]
1503 _reserved_network = IPv4Network('240.0.0.0/4')
1505 _unspecified_address = IPv4Address('0.0.0.0')
1508IPv4Address._constants = _IPv4Constants
1511class _BaseV6:
1513 """Base IPv6 object.
1515 The following methods are used by IPv6 objects in both single IP
1516 addresses and networks.
1518 """
1520 __slots__ = ()
1521 _version = 6
1522 _ALL_ONES = (2**IPV6LENGTH) - 1
1523 _HEXTET_COUNT = 8
1524 _HEX_DIGITS = frozenset('0123456789ABCDEFabcdef')
1525 _max_prefixlen = IPV6LENGTH
1527 # There are only a bunch of valid v6 netmasks, so we cache them all
1528 # when constructed (see _make_netmask()).
1529 _netmask_cache = {}
1531 @classmethod
1532 def _make_netmask(cls, arg):
1533 """Make a (netmask, prefix_len) tuple from the given argument.
1535 Argument can be:
1536 - an integer (the prefix length)
1537 - a string representing the prefix length (e.g. "24")
1538 - a string representing the prefix netmask (e.g. "255.255.255.0")
1539 """
1540 if arg not in cls._netmask_cache:
1541 if isinstance(arg, int):
1542 prefixlen = arg
1543 if not (0 <= prefixlen <= cls._max_prefixlen):
1544 cls._report_invalid_netmask(prefixlen)
1545 else:
1546 prefixlen = cls._prefix_from_prefix_string(arg)
1547 netmask = IPv6Address(cls._ip_int_from_prefix(prefixlen))
1548 cls._netmask_cache[arg] = netmask, prefixlen
1549 return cls._netmask_cache[arg]
1551 @classmethod
1552 def _ip_int_from_string(cls, ip_str):
1553 """Turn an IPv6 ip_str into an integer.
1555 Args:
1556 ip_str: A string, the IPv6 ip_str.
1558 Returns:
1559 An int, the IPv6 address
1561 Raises:
1562 AddressValueError: if ip_str isn't a valid IPv6 Address.
1564 """
1565 if not ip_str:
1566 raise AddressValueError('Address cannot be empty')
1568 parts = ip_str.split(':')
1570 # An IPv6 address needs at least 2 colons (3 parts).
1571 _min_parts = 3
1572 if len(parts) < _min_parts:
1573 msg = "At least %d parts expected in %r" % (_min_parts, ip_str)
1574 raise AddressValueError(msg)
1576 # If the address has an IPv4-style suffix, convert it to hexadecimal.
1577 if '.' in parts[-1]:
1578 try:
1579 ipv4_int = IPv4Address(parts.pop())._ip
1580 except AddressValueError as exc:
1581 raise AddressValueError("%s in %r" % (exc, ip_str)) from None
1582 parts.append('%x' % ((ipv4_int >> 16) & 0xFFFF))
1583 parts.append('%x' % (ipv4_int & 0xFFFF))
1585 # An IPv6 address can't have more than 8 colons (9 parts).
1586 # The extra colon comes from using the "::" notation for a single
1587 # leading or trailing zero part.
1588 _max_parts = cls._HEXTET_COUNT + 1
1589 if len(parts) > _max_parts:
1590 msg = "At most %d colons permitted in %r" % (_max_parts-1, ip_str)
1591 raise AddressValueError(msg)
1593 # Disregarding the endpoints, find '::' with nothing in between.
1594 # This indicates that a run of zeroes has been skipped.
1595 skip_index = None
1596 for i in range(1, len(parts) - 1):
1597 if not parts[i]:
1598 if skip_index is not None:
1599 # Can't have more than one '::'
1600 msg = "At most one '::' permitted in %r" % ip_str
1601 raise AddressValueError(msg)
1602 skip_index = i
1604 # parts_hi is the number of parts to copy from above/before the '::'
1605 # parts_lo is the number of parts to copy from below/after the '::'
1606 if skip_index is not None:
1607 # If we found a '::', then check if it also covers the endpoints.
1608 parts_hi = skip_index
1609 parts_lo = len(parts) - skip_index - 1
1610 if not parts[0]:
1611 parts_hi -= 1
1612 if parts_hi:
1613 msg = "Leading ':' only permitted as part of '::' in %r"
1614 raise AddressValueError(msg % ip_str) # ^: requires ^::
1615 if not parts[-1]:
1616 parts_lo -= 1
1617 if parts_lo:
1618 msg = "Trailing ':' only permitted as part of '::' in %r"
1619 raise AddressValueError(msg % ip_str) # :$ requires ::$
1620 parts_skipped = cls._HEXTET_COUNT - (parts_hi + parts_lo)
1621 if parts_skipped < 1:
1622 msg = "Expected at most %d other parts with '::' in %r"
1623 raise AddressValueError(msg % (cls._HEXTET_COUNT-1, ip_str))
1624 else:
1625 # Otherwise, allocate the entire address to parts_hi. The
1626 # endpoints could still be empty, but _parse_hextet() will check
1627 # for that.
1628 if len(parts) != cls._HEXTET_COUNT:
1629 msg = "Exactly %d parts expected without '::' in %r"
1630 raise AddressValueError(msg % (cls._HEXTET_COUNT, ip_str))
1631 if not parts[0]:
1632 msg = "Leading ':' only permitted as part of '::' in %r"
1633 raise AddressValueError(msg % ip_str) # ^: requires ^::
1634 if not parts[-1]:
1635 msg = "Trailing ':' only permitted as part of '::' in %r"
1636 raise AddressValueError(msg % ip_str) # :$ requires ::$
1637 parts_hi = len(parts)
1638 parts_lo = 0
1639 parts_skipped = 0
1641 try:
1642 # Now, parse the hextets into a 128-bit integer.
1643 ip_int = 0
1644 for i in range(parts_hi):
1645 ip_int <<= 16
1646 ip_int |= cls._parse_hextet(parts[i])
1647 ip_int <<= 16 * parts_skipped
1648 for i in range(-parts_lo, 0):
1649 ip_int <<= 16
1650 ip_int |= cls._parse_hextet(parts[i])
1651 return ip_int
1652 except ValueError as exc:
1653 raise AddressValueError("%s in %r" % (exc, ip_str)) from None
1655 @classmethod
1656 def _parse_hextet(cls, hextet_str):
1657 """Convert an IPv6 hextet string into an integer.
1659 Args:
1660 hextet_str: A string, the number to parse.
1662 Returns:
1663 The hextet as an integer.
1665 Raises:
1666 ValueError: if the input isn't strictly a hex number from
1667 [0..FFFF].
1669 """
1670 # Whitelist the characters, since int() allows a lot of bizarre stuff.
1671 if not cls._HEX_DIGITS.issuperset(hextet_str):
1672 raise ValueError("Only hex digits permitted in %r" % hextet_str)
1673 # We do the length check second, since the invalid character error
1674 # is likely to be more informative for the user
1675 if len(hextet_str) > 4:
1676 msg = "At most 4 characters permitted in %r"
1677 raise ValueError(msg % hextet_str)
1678 # Length check means we can skip checking the integer value
1679 return int(hextet_str, 16)
1681 @classmethod
1682 def _compress_hextets(cls, hextets):
1683 """Compresses a list of hextets.
1685 Compresses a list of strings, replacing the longest continuous
1686 sequence of "0" in the list with "" and adding empty strings at
1687 the beginning or at the end of the string such that subsequently
1688 calling ":".join(hextets) will produce the compressed version of
1689 the IPv6 address.
1691 Args:
1692 hextets: A list of strings, the hextets to compress.
1694 Returns:
1695 A list of strings.
1697 """
1698 best_doublecolon_start = -1
1699 best_doublecolon_len = 0
1700 doublecolon_start = -1
1701 doublecolon_len = 0
1702 for index, hextet in enumerate(hextets):
1703 if hextet == '0':
1704 doublecolon_len += 1
1705 if doublecolon_start == -1:
1706 # Start of a sequence of zeros.
1707 doublecolon_start = index
1708 if doublecolon_len > best_doublecolon_len:
1709 # This is the longest sequence of zeros so far.
1710 best_doublecolon_len = doublecolon_len
1711 best_doublecolon_start = doublecolon_start
1712 else:
1713 doublecolon_len = 0
1714 doublecolon_start = -1
1716 if best_doublecolon_len > 1:
1717 best_doublecolon_end = (best_doublecolon_start +
1718 best_doublecolon_len)
1719 # For zeros at the end of the address.
1720 if best_doublecolon_end == len(hextets):
1721 hextets += ['']
1722 hextets[best_doublecolon_start:best_doublecolon_end] = ['']
1723 # For zeros at the beginning of the address.
1724 if best_doublecolon_start == 0:
1725 hextets = [''] + hextets
1727 return hextets
1729 @classmethod
1730 def _string_from_ip_int(cls, ip_int=None):
1731 """Turns a 128-bit integer into hexadecimal notation.
1733 Args:
1734 ip_int: An integer, the IP address.
1736 Returns:
1737 A string, the hexadecimal representation of the address.
1739 Raises:
1740 ValueError: The address is bigger than 128 bits of all ones.
1742 """
1743 if ip_int is None:
1744 ip_int = int(cls._ip)
1746 if ip_int > cls._ALL_ONES:
1747 raise ValueError('IPv6 address is too large')
1749 hex_str = '%032x' % ip_int
1750 hextets = ['%x' % int(hex_str[x:x+4], 16) for x in range(0, 32, 4)]
1752 hextets = cls._compress_hextets(hextets)
1753 return ':'.join(hextets)
1755 def _explode_shorthand_ip_string(self):
1756 """Expand a shortened IPv6 address.
1758 Args:
1759 ip_str: A string, the IPv6 address.
1761 Returns:
1762 A string, the expanded IPv6 address.
1764 """
1765 if isinstance(self, IPv6Network):
1766 ip_str = str(self.network_address)
1767 elif isinstance(self, IPv6Interface):
1768 ip_str = str(self.ip)
1769 else:
1770 ip_str = str(self)
1772 ip_int = self._ip_int_from_string(ip_str)
1773 hex_str = '%032x' % ip_int
1774 parts = [hex_str[x:x+4] for x in range(0, 32, 4)]
1775 if isinstance(self, (_BaseNetwork, IPv6Interface)):
1776 return '%s/%d' % (':'.join(parts), self._prefixlen)
1777 return ':'.join(parts)
1779 def _reverse_pointer(self):
1780 """Return the reverse DNS pointer name for the IPv6 address.
1782 This implements the method described in RFC3596 2.5.
1784 """
1785 reverse_chars = self.exploded[::-1].replace(':', '')
1786 return '.'.join(reverse_chars) + '.ip6.arpa'
1788 @property
1789 def max_prefixlen(self):
1790 return self._max_prefixlen
1792 @property
1793 def version(self):
1794 return self._version
1797class IPv6Address(_BaseV6, _BaseAddress):
1799 """Represent and manipulate single IPv6 Addresses."""
1801 __slots__ = ('_ip', '__weakref__')
1803 def __init__(self, address):
1804 """Instantiate a new IPv6 address object.
1806 Args:
1807 address: A string or integer representing the IP
1809 Additionally, an integer can be passed, so
1810 IPv6Address('2001:db8::') ==
1811 IPv6Address(42540766411282592856903984951653826560)
1812 or, more generally
1813 IPv6Address(int(IPv6Address('2001:db8::'))) ==
1814 IPv6Address('2001:db8::')
1816 Raises:
1817 AddressValueError: If address isn't a valid IPv6 address.
1819 """
1820 # Efficient constructor from integer.
1821 if isinstance(address, int):
1822 self._check_int_address(address)
1823 self._ip = address
1824 return
1826 # Constructing from a packed address
1827 if isinstance(address, bytes):
1828 self._check_packed_address(address, 16)
1829 self._ip = int.from_bytes(address, 'big')
1830 return
1832 # Assume input argument to be string or any object representation
1833 # which converts into a formatted IP string.
1834 addr_str = str(address)
1835 if '/' in addr_str:
1836 raise AddressValueError("Unexpected '/' in %r" % address)
1837 self._ip = self._ip_int_from_string(addr_str)
1839 @property
1840 def packed(self):
1841 """The binary representation of this address."""
1842 return v6_int_to_packed(self._ip)
1844 @property
1845 def is_multicast(self):
1846 """Test if the address is reserved for multicast use.
1848 Returns:
1849 A boolean, True if the address is a multicast address.
1850 See RFC 2373 2.7 for details.
1852 """
1853 return self in self._constants._multicast_network
1855 @property
1856 def is_reserved(self):
1857 """Test if the address is otherwise IETF reserved.
1859 Returns:
1860 A boolean, True if the address is within one of the
1861 reserved IPv6 Network ranges.
1863 """
1864 return any(self in x for x in self._constants._reserved_networks)
1866 @property
1867 def is_link_local(self):
1868 """Test if the address is reserved for link-local.
1870 Returns:
1871 A boolean, True if the address is reserved per RFC 4291.
1873 """
1874 return self in self._constants._linklocal_network
1876 @property
1877 def is_site_local(self):
1878 """Test if the address is reserved for site-local.
1880 Note that the site-local address space has been deprecated by RFC 3879.
1881 Use is_private to test if this address is in the space of unique local
1882 addresses as defined by RFC 4193.
1884 Returns:
1885 A boolean, True if the address is reserved per RFC 3513 2.5.6.
1887 """
1888 return self in self._constants._sitelocal_network
1890 @property
1891 @functools.lru_cache()
1892 def is_private(self):
1893 """Test if this address is allocated for private networks.
1895 Returns:
1896 A boolean, True if the address is reserved per
1897 iana-ipv6-special-registry.
1899 """
1900 return any(self in net for net in self._constants._private_networks)
1902 @property
1903 def is_global(self):
1904 """Test if this address is allocated for public networks.
1906 Returns:
1907 A boolean, true if the address is not reserved per
1908 iana-ipv6-special-registry.
1910 """
1911 return not self.is_private
1913 @property
1914 def is_unspecified(self):
1915 """Test if the address is unspecified.
1917 Returns:
1918 A boolean, True if this is the unspecified address as defined in
1919 RFC 2373 2.5.2.
1921 """
1922 return self._ip == 0
1924 @property
1925 def is_loopback(self):
1926 """Test if the address is a loopback address.
1928 Returns:
1929 A boolean, True if the address is a loopback address as defined in
1930 RFC 2373 2.5.3.
1932 """
1933 return self._ip == 1
1935 @property
1936 def ipv4_mapped(self):
1937 """Return the IPv4 mapped address.
1939 Returns:
1940 If the IPv6 address is a v4 mapped address, return the
1941 IPv4 mapped address. Return None otherwise.
1943 """
1944 if (self._ip >> 32) != 0xFFFF:
1945 return None
1946 return IPv4Address(self._ip & 0xFFFFFFFF)
1948 @property
1949 def teredo(self):
1950 """Tuple of embedded teredo IPs.
1952 Returns:
1953 Tuple of the (server, client) IPs or None if the address
1954 doesn't appear to be a teredo address (doesn't start with
1955 2001::/32)
1957 """
1958 if (self._ip >> 96) != 0x20010000:
1959 return None
1960 return (IPv4Address((self._ip >> 64) & 0xFFFFFFFF),
1961 IPv4Address(~self._ip & 0xFFFFFFFF))
1963 @property
1964 def sixtofour(self):
1965 """Return the IPv4 6to4 embedded address.
1967 Returns:
1968 The IPv4 6to4-embedded address if present or None if the
1969 address doesn't appear to contain a 6to4 embedded address.
1971 """
1972 if (self._ip >> 112) != 0x2002:
1973 return None
1974 return IPv4Address((self._ip >> 80) & 0xFFFFFFFF)
1977class IPv6Interface(IPv6Address):
1979 def __init__(self, address):
1980 addr, mask = self._split_addr_prefix(address)
1982 IPv6Address.__init__(self, addr)
1983 self.network = IPv6Network((addr, mask), strict=False)
1984 self.netmask = self.network.netmask
1985 self._prefixlen = self.network._prefixlen
1987 @functools.cached_property
1988 def hostmask(self):
1989 return self.network.hostmask
1991 def __str__(self):
1992 return '%s/%d' % (self._string_from_ip_int(self._ip),
1993 self._prefixlen)
1995 def __eq__(self, other):
1996 address_equal = IPv6Address.__eq__(self, other)
1997 if not address_equal or address_equal is NotImplemented:
1998 return address_equal
1999 try:
2000 return self.network == other.network
2001 except AttributeError:
2002 # An interface with an associated network is NOT the
2003 # same as an unassociated address. That's why the hash
2004 # takes the extra info into account.
2005 return False
2007 def __lt__(self, other):
2008 address_less = IPv6Address.__lt__(self, other)
2009 if address_less is NotImplemented:
2010 return NotImplemented
2011 try:
2012 return (self.network < other.network or
2013 self.network == other.network and address_less)
2014 except AttributeError:
2015 # We *do* allow addresses and interfaces to be sorted. The
2016 # unassociated address is considered less than all interfaces.
2017 return False
2019 def __hash__(self):
2020 return self._ip ^ self._prefixlen ^ int(self.network.network_address)
2022 __reduce__ = _IPAddressBase.__reduce__
2024 @property
2025 def ip(self):
2026 return IPv6Address(self._ip)
2028 @property
2029 def with_prefixlen(self):
2030 return '%s/%s' % (self._string_from_ip_int(self._ip),
2031 self._prefixlen)
2033 @property
2034 def with_netmask(self):
2035 return '%s/%s' % (self._string_from_ip_int(self._ip),
2036 self.netmask)
2038 @property
2039 def with_hostmask(self):
2040 return '%s/%s' % (self._string_from_ip_int(self._ip),
2041 self.hostmask)
2043 @property
2044 def is_unspecified(self):
2045 return self._ip == 0 and self.network.is_unspecified
2047 @property
2048 def is_loopback(self):
2049 return self._ip == 1 and self.network.is_loopback
2052class IPv6Network(_BaseV6, _BaseNetwork):
2054 """This class represents and manipulates 128-bit IPv6 networks.
2056 Attributes: [examples for IPv6('2001:db8::1000/124')]
2057 .network_address: IPv6Address('2001:db8::1000')
2058 .hostmask: IPv6Address('::f')
2059 .broadcast_address: IPv6Address('2001:db8::100f')
2060 .netmask: IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff:ffff:fff0')
2061 .prefixlen: 124
2063 """
2065 # Class to use when creating address objects
2066 _address_class = IPv6Address
2068 def __init__(self, address, strict=True):
2069 """Instantiate a new IPv6 Network object.
2071 Args:
2072 address: A string or integer representing the IPv6 network or the
2073 IP and prefix/netmask.
2074 '2001:db8::/128'
2075 '2001:db8:0000:0000:0000:0000:0000:0000/128'
2076 '2001:db8::'
2077 are all functionally the same in IPv6. That is to say,
2078 failing to provide a subnetmask will create an object with
2079 a mask of /128.
2081 Additionally, an integer can be passed, so
2082 IPv6Network('2001:db8::') ==
2083 IPv6Network(42540766411282592856903984951653826560)
2084 or, more generally
2085 IPv6Network(int(IPv6Network('2001:db8::'))) ==
2086 IPv6Network('2001:db8::')
2088 strict: A boolean. If true, ensure that we have been passed
2089 A true network address, eg, 2001:db8::1000/124 and not an
2090 IP address on a network, eg, 2001:db8::1/124.
2092 Raises:
2093 AddressValueError: If address isn't a valid IPv6 address.
2094 NetmaskValueError: If the netmask isn't valid for
2095 an IPv6 address.
2096 ValueError: If strict was True and a network address was not
2097 supplied.
2098 """
2099 addr, mask = self._split_addr_prefix(address)
2101 self.network_address = IPv6Address(addr)
2102 self.netmask, self._prefixlen = self._make_netmask(mask)
2103 packed = int(self.network_address)
2104 if packed & int(self.netmask) != packed:
2105 if strict:
2106 raise ValueError('%s has host bits set' % self)
2107 else:
2108 self.network_address = IPv6Address(packed &
2109 int(self.netmask))
2111 if self._prefixlen == (self._max_prefixlen - 1):
2112 self.hosts = self.__iter__
2114 def hosts(self):
2115 """Generate Iterator over usable hosts in a network.
2117 This is like __iter__ except it doesn't return the
2118 Subnet-Router anycast address.
2120 """
2121 network = int(self.network_address)
2122 broadcast = int(self.broadcast_address)
2123 for x in range(network + 1, broadcast + 1):
2124 yield self._address_class(x)
2126 @property
2127 def is_site_local(self):
2128 """Test if the address is reserved for site-local.
2130 Note that the site-local address space has been deprecated by RFC 3879.
2131 Use is_private to test if this address is in the space of unique local
2132 addresses as defined by RFC 4193.
2134 Returns:
2135 A boolean, True if the address is reserved per RFC 3513 2.5.6.
2137 """
2138 return (self.network_address.is_site_local and
2139 self.broadcast_address.is_site_local)
2142class _IPv6Constants:
2144 _linklocal_network = IPv6Network('fe80::/10')
2146 _multicast_network = IPv6Network('ff00::/8')
2148 _private_networks = [
2149 IPv6Network('::1/128'),
2150 IPv6Network('::/128'),
2151 IPv6Network('::ffff:0:0/96'),
2152 IPv6Network('100::/64'),
2153 IPv6Network('2001::/23'),
2154 IPv6Network('2001:2::/48'),
2155 IPv6Network('2001:db8::/32'),
2156 IPv6Network('2001:10::/28'),
2157 IPv6Network('fc00::/7'),
2158 IPv6Network('fe80::/10'),
2159 ]
2161 _reserved_networks = [
2162 IPv6Network('::/8'), IPv6Network('100::/8'),
2163 IPv6Network('200::/7'), IPv6Network('400::/6'),
2164 IPv6Network('800::/5'), IPv6Network('1000::/4'),
2165 IPv6Network('4000::/3'), IPv6Network('6000::/3'),
2166 IPv6Network('8000::/3'), IPv6Network('A000::/3'),
2167 IPv6Network('C000::/3'), IPv6Network('E000::/4'),
2168 IPv6Network('F000::/5'), IPv6Network('F800::/6'),
2169 IPv6Network('FE00::/9'),
2170 ]
2172 _sitelocal_network = IPv6Network('fec0::/10')
2175IPv6Address._constants = _IPv6Constants