1 :mod:`ipaddress` --- IPv4/IPv6 manipulation library 2 =================================================== 3 4 .. module:: ipaddress 5 :synopsis: IPv4/IPv6 manipulation library. 6 7 .. moduleauthor:: Peter Moody 8 9 **Source code:** :source:`Lib/ipaddress.py` 10 11 -------------- 12 13 :mod:`ipaddress` provides the capabilities to create, manipulate and 14 operate on IPv4 and IPv6 addresses and networks. 15 16 The functions and classes in this module make it straightforward to handle 17 various tasks related to IP addresses, including checking whether or not two 18 hosts are on the same subnet, iterating over all hosts in a particular 19 subnet, checking whether or not a string represents a valid IP address or 20 network definition, and so on. 21 22 This is the full module API referencefor an overview and introduction, see 23 :ref:`ipaddress-howto`. 24 25 .. versionadded:: 3.3 26 27 .. testsetup:: 28 29 import ipaddress 30 from ipaddress import ( 31 ip_network, IPv4Address, IPv4Interface, IPv4Network, 32 ) 33 34 Convenience factory functions 35 ----------------------------- 36 37 The :mod:`ipaddress` module provides factory functions to conveniently create 38 IP addresses, networks and interfaces: 39 40 .. function:: ip_address(address) 41 42 Return an :class:`IPv4Address` or :class:`IPv6Address` object depending on 43 the IP address passed as argument. Either IPv4 or IPv6 addresses may be 44 supplied; integers less than 2**32 will be considered to be IPv4 by default. 45 A :exc:`ValueError` is raised if *address* does not represent a valid IPv4 46 or IPv6 address. 47 48 >>> ipaddress.ip_address('192.168.0.1') 49 IPv4Address('192.168.0.1') 50 >>> ipaddress.ip_address('2001:db8::') 51 IPv6Address('2001:db8::') 52 53 54 .. function:: ip_network(address, strict=True) 55 56 Return an :class:`IPv4Network` or :class:`IPv6Network` object depending on 57 the IP address passed as argument. *address* is a string or integer 58 representing the IP network. Either IPv4 or IPv6 networks may be supplied; 59 integers less than 2**32 will be considered to be IPv4 by default. *strict* 60 is passed to :class:`IPv4Network` or :class:`IPv6Network` constructor. A 61 :exc:`ValueError` is raised if *address* does not represent a valid IPv4 or 62 IPv6 address, or if the network has host bits set. 63 64 >>> ipaddress.ip_network('192.168.0.0/28') 65 IPv4Network('192.168.0.0/28') 66 67 68 .. function:: ip_interface(address) 69 70 Return an :class:`IPv4Interface` or :class:`IPv6Interface` object depending 71 on the IP address passed as argument. *address* is a string or integer 72 representing the IP address. Either IPv4 or IPv6 addresses may be supplied; 73 integers less than 2**32 will be considered to be IPv4 by default. A 74 :exc:`ValueError` is raised if *address* does not represent a valid IPv4 or 75 IPv6 address. 76 77 One downside of these convenience functions is that the need to handle both 78 IPv4 and IPv6 formats means that error messages provide minimal 79 information on the precise error, as the functions don't know whether the 80 IPv4 or IPv6 format was intended. More detailed error reporting can be 81 obtained by calling the appropriate version specific class constructors 82 directly. 83 84 85 IP Addresses 86 ------------ 87 88 Address objects 89 ^^^^^^^^^^^^^^^ 90 91 The :class:`IPv4Address` and :class:`IPv6Address` objects share a lot of common 92 attributes. Some attributes that are only meaningful for IPv6 addresses are 93 also implemented by :class:`IPv4Address` objects, in order to make it easier to 94 write code that handles both IP versions correctly. Address objects are 95 :term:`hashable`, so they can be used as keys in dictionaries. 96 97 .. class:: IPv4Address(address) 98 99 Construct an IPv4 address. An :exc:`AddressValueError` is raised if 100 *address* is not a valid IPv4 address. 101 102 The following constitutes a valid IPv4 address: 103 104 1. A string in decimal-dot notation, consisting of four decimal integers in 105 the inclusive range 0--255, separated by dots (e.g. ``192.168.0.1``). Each 106 integer represents an octet (byte) in the address. Leading zeroes are 107 tolerated only for values less than 8 (as there is no ambiguity 108 between the decimal and octal interpretations of such strings). 109 2. An integer that fits into 32 bits. 110 3. An integer packed into a :class:`bytes` object of length 4 (most 111 significant octet first). 112 113 >>> ipaddress.IPv4Address('192.168.0.1') 114 IPv4Address('192.168.0.1') 115 >>> ipaddress.IPv4Address(3232235521) 116 IPv4Address('192.168.0.1') 117 >>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01') 118 IPv4Address('192.168.0.1') 119 120 .. attribute:: version 121 122 The appropriate version number: ``4`` for IPv4, ``6`` for IPv6. 123 124 .. attribute:: max_prefixlen 125 126 The total number of bits in the address representation for this 127 version: ``32`` for IPv4, ``128`` for IPv6. 128 129 The prefix defines the number of leading bits in an address that 130 are compared to determine whether or not an address is part of a 131 network. 132 133 .. attribute:: compressed 134 .. attribute:: exploded 135 136 The string representation in dotted decimal notation. Leading zeroes 137 are never included in the representation. 138 139 As IPv4 does not define a shorthand notation for addresses with octets 140 set to zero, these two attributes are always the same as ``str(addr)`` 141 for IPv4 addresses. Exposing these attributes makes it easier to 142 write display code that can handle both IPv4 and IPv6 addresses. 143 144 .. attribute:: packed 145 146 The binary representation of this address - a :class:`bytes` object of 147 the appropriate length (most significant octet first). This is 4 bytes 148 for IPv4 and 16 bytes for IPv6. 149 150 .. attribute:: reverse_pointer 151 152 The name of the reverse DNS PTR record for the IP address, e.g.:: 153 154 >>> ipaddress.ip_address("127.0.0.1").reverse_pointer 155 '1.0.0.127.in-addr.arpa' 156 >>> ipaddress.ip_address("2001:db8::1").reverse_pointer 157 '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' 158 159 This is the name that could be used for performing a PTR lookup, not the 160 resolved hostname itself. 161 162 .. versionadded:: 3.5 163 164 .. attribute:: is_multicast 165 166 ``True`` if the address is reserved for multicast use. See 167 :RFC:`3171` (for IPv4) or :RFC:`2373` (for IPv6). 168 169 .. attribute:: is_private 170 171 ``True`` if the address is allocated for private networks. See 172 iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_ 173 (for IPv6). 174 175 .. attribute:: is_global 176 177 ``True`` if the address is allocated for public networks. See 178 iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_ 179 (for IPv6). 180 181 .. versionadded:: 3.4 182 183 .. attribute:: is_unspecified 184 185 ``True`` if the address is unspecified. See :RFC:`5735` (for IPv4) 186 or :RFC:`2373` (for IPv6). 187 188 .. attribute:: is_reserved 189 190 ``True`` if the address is otherwise IETF reserved. 191 192 .. attribute:: is_loopback 193 194 ``True`` if this is a loopback address. See :RFC:`3330` (for IPv4) 195 or :RFC:`2373` (for IPv6). 196 197 .. attribute:: is_link_local 198 199 ``True`` if the address is reserved for link-local usage. See 200 :RFC:`3927`. 201 202 .. _iana-ipv4-special-registry: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml 203 .. _iana-ipv6-special-registry: https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml 204 205 206 .. class:: IPv6Address(address) 207 208 Construct an IPv6 address. An :exc:`AddressValueError` is raised if 209 *address* is not a valid IPv6 address. 210 211 The following constitutes a valid IPv6 address: 212 213 1. A string consisting of eight groups of four hexadecimal digits, each 214 group representing 16 bits. The groups are separated by colons. 215 This describes an *exploded* (longhand) notation. The string can 216 also be *compressed* (shorthand notation) by various means. See 217 :RFC:`4291` for details. For example, 218 ``"0000:0000:0000:0000:0000:0abc:0007:0def"`` can be compressed to 219 ``"::abc:7:def"``. 220 2. An integer that fits into 128 bits. 221 3. An integer packed into a :class:`bytes` object of length 16, big-endian. 222 223 >>> ipaddress.IPv6Address('2001:db8::1000') 224 IPv6Address('2001:db8::1000') 225 226 .. attribute:: compressed 227 228 The short form of the address representation, with leading zeroes in 229 groups omitted and the longest sequence of groups consisting entirely of 230 zeroes collapsed to a single empty group. 231 232 This is also the value returned by ``str(addr)`` for IPv6 addresses. 233 234 .. attribute:: exploded 235 236 The long form of the address representation, with all leading zeroes and 237 groups consisting entirely of zeroes included. 238 239 240 For the following attributes, see the corresponding documentation of the 241 :class:`IPv4Address` class: 242 243 .. attribute:: packed 244 .. attribute:: reverse_pointer 245 .. attribute:: version 246 .. attribute:: max_prefixlen 247 .. attribute:: is_multicast 248 .. attribute:: is_private 249 .. attribute:: is_global 250 .. attribute:: is_unspecified 251 .. attribute:: is_reserved 252 .. attribute:: is_loopback 253 .. attribute:: is_link_local 254 255 .. versionadded:: 3.4 256 is_global 257 258 .. attribute:: is_site_local 259 260 ``True`` if the address is reserved for site-local usage. Note that 261 the site-local address space has been deprecated by :RFC:`3879`. Use 262 :attr:`~IPv4Address.is_private` to test if this address is in the 263 space of unique local addresses as defined by :RFC:`4193`. 264 265 .. attribute:: ipv4_mapped 266 267 For addresses that appear to be IPv4 mapped addresses (starting with 268 ``::FFFF/96``), this property will report the embedded IPv4 address. 269 For any other address, this property will be ``None``. 270 271 .. attribute:: sixtofour 272 273 For addresses that appear to be 6to4 addresses (starting with 274 ``2002::/16``) as defined by :RFC:`3056`, this property will report 275 the embedded IPv4 address. For any other address, this property will 276 be ``None``. 277 278 .. attribute:: teredo 279 280 For addresses that appear to be Teredo addresses (starting with 281 ``2001::/32``) as defined by :RFC:`4380`, this property will report 282 the embedded ``(server, client)`` IP address pair. For any other 283 address, this property will be ``None``. 284 285 286 Conversion to Strings and Integers 287 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 288 289 To interoperate with networking interfaces such as the socket module, 290 addresses must be converted to strings or integers. This is handled using 291 the :func:`str` and :func:`int` builtin functions:: 292 293 >>> str(ipaddress.IPv4Address('192.168.0.1')) 294 '192.168.0.1' 295 >>> int(ipaddress.IPv4Address('192.168.0.1')) 296 3232235521 297 >>> str(ipaddress.IPv6Address('::1')) 298 '::1' 299 >>> int(ipaddress.IPv6Address('::1')) 300 1 301 302 303 Operators 304 ^^^^^^^^^ 305 306 Address objects support some operators. Unless stated otherwise, operators can 307 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 308 IPv6). 309 310 311 Comparison operators 312 """""""""""""""""""" 313 314 Address objects can be compared with the usual set of comparison operators. Some 315 examples:: 316 317 >>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1') 318 True 319 >>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1') 320 False 321 >>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1') 322 True 323 324 325 Arithmetic operators 326 """""""""""""""""""" 327 328 Integers can be added to or subtracted from address objects. Some examples:: 329 330 >>> IPv4Address('127.0.0.2') + 3 331 IPv4Address('127.0.0.5') 332 >>> IPv4Address('127.0.0.2') - 3 333 IPv4Address('126.255.255.255') 334 >>> IPv4Address('255.255.255.255') + 1 335 Traceback (most recent call last): 336 File "<stdin>", line 1, in <module> 337 ipaddress.AddressValueError: 4294967296 (>= 2**32) is not permitted as an IPv4 address 338 339 340 IP Network definitions 341 ---------------------- 342 343 The :class:`IPv4Network` and :class:`IPv6Network` objects provide a mechanism 344 for defining and inspecting IP network definitions. A network definition 345 consists of a *mask* and a *network address*, and as such defines a range of 346 IP addresses that equal the network address when masked (binary AND) with the 347 mask. For example, a network definition with the mask ``255.255.255.0`` and 348 the network address ``192.168.1.0`` consists of IP addresses in the inclusive 349 range ``192.168.1.0`` to ``192.168.1.255``. 350 351 352 Prefix, net mask and host mask 353 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 354 355 There are several equivalent ways to specify IP network masks. A *prefix* 356 ``/<nbits>`` is a notation that denotes how many high-order bits are set in 357 the network mask. A *net mask* is an IP address with some number of 358 high-order bits set. Thus the prefix ``/24`` is equivalent to the net mask 359 ``255.255.255.0`` in IPv4, or ``ffff:ff00::`` in IPv6. In addition, a 360 *host mask* is the logical inverse of a *net mask*, and is sometimes used 361 (for example in Cisco access control lists) to denote a network mask. The 362 host mask equivalent to ``/24`` in IPv4 is ``0.0.0.255``. 363 364 365 Network objects 366 ^^^^^^^^^^^^^^^ 367 368 All attributes implemented by address objects are implemented by network 369 objects as well. In addition, network objects implement additional attributes. 370 All of these are common between :class:`IPv4Network` and :class:`IPv6Network`, 371 so to avoid duplication they are only documented for :class:`IPv4Network`. 372 Network objects are :term:`hashable`, so they can be used as keys in 373 dictionaries. 374 375 .. class:: IPv4Network(address, strict=True) 376 377 Construct an IPv4 network definition. *address* can be one of the following: 378 379 1. A string consisting of an IP address and an optional mask, separated by 380 a slash (``/``). The IP address is the network address, and the mask 381 can be either a single number, which means it's a *prefix*, or a string 382 representation of an IPv4 address. If it's the latter, the mask is 383 interpreted as a *net mask* if it starts with a non-zero field, or as a 384 *host mask* if it starts with a zero field, with the single exception of 385 an all-zero mask which is treated as a *net mask*. If no mask is provided, 386 it's considered to be ``/32``. 387 388 For example, the following *address* specifications are equivalent: 389 ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and 390 ``192.168.1.0/0.0.0.255``. 391 392 2. An integer that fits into 32 bits. This is equivalent to a 393 single-address network, with the network address being *address* and 394 the mask being ``/32``. 395 396 3. An integer packed into a :class:`bytes` object of length 4, big-endian. 397 The interpretation is similar to an integer *address*. 398 399 4. A two-tuple of an address description and a netmask, where the address 400 description is either a string, a 32-bits integer, a 4-bytes packed 401 integer, or an existing IPv4Address object; and the netmask is either 402 an integer representing the prefix length (e.g. ``24``) or a string 403 representing the prefix mask (e.g. ``255.255.255.0``). 404 405 An :exc:`AddressValueError` is raised if *address* is not a valid IPv4 406 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for 407 an IPv4 address. 408 409 If *strict* is ``True`` and host bits are set in the supplied address, 410 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out 411 to determine the appropriate network address. 412 413 Unless stated otherwise, all network methods accepting other network/address 414 objects will raise :exc:`TypeError` if the argument's IP version is 415 incompatible to ``self``. 416 417 .. versionchanged:: 3.5 418 419 Added the two-tuple form for the *address* constructor parameter. 420 421 .. attribute:: version 422 .. attribute:: max_prefixlen 423 424 Refer to the corresponding attribute documentation in 425 :class:`IPv4Address`. 426 427 .. attribute:: is_multicast 428 .. attribute:: is_private 429 .. attribute:: is_unspecified 430 .. attribute:: is_reserved 431 .. attribute:: is_loopback 432 .. attribute:: is_link_local 433 434 These attributes are true for the network as a whole if they are true 435 for both the network address and the broadcast address. 436 437 .. attribute:: network_address 438 439 The network address for the network. The network address and the 440 prefix length together uniquely define a network. 441 442 .. attribute:: broadcast_address 443 444 The broadcast address for the network. Packets sent to the broadcast 445 address should be received by every host on the network. 446 447 .. attribute:: hostmask 448 449 The host mask, as an :class:`IPv4Address` object. 450 451 .. attribute:: netmask 452 453 The net mask, as an :class:`IPv4Address` object. 454 455 .. attribute:: with_prefixlen 456 .. attribute:: compressed 457 .. attribute:: exploded 458 459 A string representation of the network, with the mask in prefix 460 notation. 461 462 ``with_prefixlen`` and ``compressed`` are always the same as 463 ``str(network)``. 464 ``exploded`` uses the exploded form the network address. 465 466 .. attribute:: with_netmask 467 468 A string representation of the network, with the mask in net mask 469 notation. 470 471 .. attribute:: with_hostmask 472 473 A string representation of the network, with the mask in host mask 474 notation. 475 476 .. attribute:: num_addresses 477 478 The total number of addresses in the network. 479 480 .. attribute:: prefixlen 481 482 Length of the network prefix, in bits. 483 484 .. method:: hosts() 485 486 Returns an iterator over the usable hosts in the network. The usable 487 hosts are all the IP addresses that belong to the network, except the 488 network address itself and the network broadcast address. For networks 489 with a mask length of 31, the network address and network broadcast 490 address are also included in the result. 491 492 >>> list(ip_network('192.0.2.0/29').hosts()) #doctest: +NORMALIZE_WHITESPACE 493 [IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'), 494 IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'), 495 IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')] 496 >>> list(ip_network('192.0.2.0/31').hosts()) 497 [IPv4Address('192.0.2.0'), IPv4Address('192.0.2.1')] 498 499 .. method:: overlaps(other) 500 501 ``True`` if this network is partly or wholly contained in *other* or 502 *other* is wholly contained in this network. 503 504 .. method:: address_exclude(network) 505 506 Computes the network definitions resulting from removing the given 507 *network* from this one. Returns an iterator of network objects. 508 Raises :exc:`ValueError` if *network* is not completely contained in 509 this network. 510 511 >>> n1 = ip_network('192.0.2.0/28') 512 >>> n2 = ip_network('192.0.2.1/32') 513 >>> list(n1.address_exclude(n2)) #doctest: +NORMALIZE_WHITESPACE 514 [IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'), 515 IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')] 516 517 .. method:: subnets(prefixlen_diff=1, new_prefix=None) 518 519 The subnets that join to make the current network definition, depending 520 on the argument values. *prefixlen_diff* is the amount our prefix 521 length should be increased by. *new_prefix* is the desired new 522 prefix of the subnets; it must be larger than our prefix. One and 523 only one of *prefixlen_diff* and *new_prefix* must be set. Returns an 524 iterator of network objects. 525 526 >>> list(ip_network('192.0.2.0/24').subnets()) 527 [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')] 528 >>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2)) #doctest: +NORMALIZE_WHITESPACE 529 [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'), 530 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')] 531 >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26)) #doctest: +NORMALIZE_WHITESPACE 532 [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'), 533 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')] 534 >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23)) 535 Traceback (most recent call last): 536 File "<stdin>", line 1, in <module> 537 raise ValueError('new prefix must be longer') 538 ValueError: new prefix must be longer 539 >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25)) 540 [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')] 541 542 .. method:: supernet(prefixlen_diff=1, new_prefix=None) 543 544 The supernet containing this network definition, depending on the 545 argument values. *prefixlen_diff* is the amount our prefix length 546 should be decreased by. *new_prefix* is the desired new prefix of 547 the supernet; it must be smaller than our prefix. One and only one 548 of *prefixlen_diff* and *new_prefix* must be set. Returns a single 549 network object. 550 551 >>> ip_network('192.0.2.0/24').supernet() 552 IPv4Network('192.0.2.0/23') 553 >>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2) 554 IPv4Network('192.0.0.0/22') 555 >>> ip_network('192.0.2.0/24').supernet(new_prefix=20) 556 IPv4Network('192.0.0.0/20') 557 558 .. method:: subnet_of(other) 559 560 Returns *True* if this network is a subnet of *other*. 561 562 >>> a = ip_network('192.168.1.0/24') 563 >>> b = ip_network('192.168.1.128/30') 564 >>> b.subnet_of(a) 565 True 566 567 .. versionadded:: 3.7 568 569 .. method:: supernet_of(other) 570 571 Returns *True* if this network is a supernet of *other*. 572 573 >>> a = ip_network('192.168.1.0/24') 574 >>> b = ip_network('192.168.1.128/30') 575 >>> a.supernet_of(b) 576 True 577 578 .. versionadded:: 3.7 579 580 .. method:: compare_networks(other) 581 582 Compare this network to *other*. In this comparison only the network 583 addresses are considered; host bits aren't. Returns either ``-1``, 584 ``0`` or ``1``. 585 586 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32')) 587 -1 588 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32')) 589 1 590 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32')) 591 0 592 593 .. deprecated:: 3.7 594 It uses the same ordering and comparison algorithm as "<", "==", and ">" 595 596 597 .. class:: IPv6Network(address, strict=True) 598 599 Construct an IPv6 network definition. *address* can be one of the following: 600 601 1. A string consisting of an IP address and an optional prefix length, 602 separated by a slash (``/``). The IP address is the network address, 603 and the prefix length must be a single number, the *prefix*. If no 604 prefix length is provided, it's considered to be ``/128``. 605 606 Note that currently expanded netmasks are not supported. That means 607 ``2001:db00::0/24`` is a valid argument while ``2001:db00::0/ffff:ff00::`` 608 not. 609 610 2. An integer that fits into 128 bits. This is equivalent to a 611 single-address network, with the network address being *address* and 612 the mask being ``/128``. 613 614 3. An integer packed into a :class:`bytes` object of length 16, big-endian. 615 The interpretation is similar to an integer *address*. 616 617 4. A two-tuple of an address description and a netmask, where the address 618 description is either a string, a 128-bits integer, a 16-bytes packed 619 integer, or an existing IPv6Address object; and the netmask is an 620 integer representing the prefix length. 621 622 An :exc:`AddressValueError` is raised if *address* is not a valid IPv6 623 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for 624 an IPv6 address. 625 626 If *strict* is ``True`` and host bits are set in the supplied address, 627 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out 628 to determine the appropriate network address. 629 630 .. versionchanged:: 3.5 631 632 Added the two-tuple form for the *address* constructor parameter. 633 634 .. attribute:: version 635 .. attribute:: max_prefixlen 636 .. attribute:: is_multicast 637 .. attribute:: is_private 638 .. attribute:: is_unspecified 639 .. attribute:: is_reserved 640 .. attribute:: is_loopback 641 .. attribute:: is_link_local 642 .. attribute:: network_address 643 .. attribute:: broadcast_address 644 .. attribute:: hostmask 645 .. attribute:: netmask 646 .. attribute:: with_prefixlen 647 .. attribute:: compressed 648 .. attribute:: exploded 649 .. attribute:: with_netmask 650 .. attribute:: with_hostmask 651 .. attribute:: num_addresses 652 .. attribute:: prefixlen 653 .. method:: hosts() 654 655 Returns an iterator over the usable hosts in the network. The usable 656 hosts are all the IP addresses that belong to the network, except the 657 Subnet-Router anycast address. For networks with a mask length of 127, 658 the Subnet-Router anycast address is also included in the result. 659 660 .. method:: overlaps(other) 661 .. method:: address_exclude(network) 662 .. method:: subnets(prefixlen_diff=1, new_prefix=None) 663 .. method:: supernet(prefixlen_diff=1, new_prefix=None) 664 .. method:: subnet_of(other) 665 .. method:: supernet_of(other) 666 .. method:: compare_networks(other) 667 668 Refer to the corresponding attribute documentation in 669 :class:`IPv4Network`. 670 671 .. attribute:: is_site_local 672 673 These attribute is true for the network as a whole if it is true 674 for both the network address and the broadcast address. 675 676 677 Operators 678 ^^^^^^^^^ 679 680 Network objects support some operators. Unless stated otherwise, operators can 681 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 682 IPv6). 683 684 685 Logical operators 686 """"""""""""""""" 687 688 Network objects can be compared with the usual set of logical operators. 689 Network objects are ordered first by network address, then by net mask. 690 691 692 Iteration 693 """"""""" 694 695 Network objects can be iterated to list all the addresses belonging to the 696 network. For iteration, *all* hosts are returned, including unusable hosts 697 (for usable hosts, use the :meth:`~IPv4Network.hosts` method). An 698 example:: 699 700 >>> for addr in IPv4Network('192.0.2.0/28'): 701 ... addr 702 ... 703 IPv4Address('192.0.2.0') 704 IPv4Address('192.0.2.1') 705 IPv4Address('192.0.2.2') 706 IPv4Address('192.0.2.3') 707 IPv4Address('192.0.2.4') 708 IPv4Address('192.0.2.5') 709 IPv4Address('192.0.2.6') 710 IPv4Address('192.0.2.7') 711 IPv4Address('192.0.2.8') 712 IPv4Address('192.0.2.9') 713 IPv4Address('192.0.2.10') 714 IPv4Address('192.0.2.11') 715 IPv4Address('192.0.2.12') 716 IPv4Address('192.0.2.13') 717 IPv4Address('192.0.2.14') 718 IPv4Address('192.0.2.15') 719 720 721 Networks as containers of addresses 722 """"""""""""""""""""""""""""""""""" 723 724 Network objects can act as containers of addresses. Some examples:: 725 726 >>> IPv4Network('192.0.2.0/28')[0] 727 IPv4Address('192.0.2.0') 728 >>> IPv4Network('192.0.2.0/28')[15] 729 IPv4Address('192.0.2.15') 730 >>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28') 731 True 732 >>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28') 733 False 734 735 736 Interface objects 737 ----------------- 738 739 Interface objects are :term:`hashable`, so they can be used as keys in 740 dictionaries. 741 742 .. class:: IPv4Interface(address) 743 744 Construct an IPv4 interface. The meaning of *address* is as in the 745 constructor of :class:`IPv4Network`, except that arbitrary host addresses 746 are always accepted. 747 748 :class:`IPv4Interface` is a subclass of :class:`IPv4Address`, so it inherits 749 all the attributes from that class. In addition, the following attributes 750 are available: 751 752 .. attribute:: ip 753 754 The address (:class:`IPv4Address`) without network information. 755 756 >>> interface = IPv4Interface('192.0.2.5/24') 757 >>> interface.ip 758 IPv4Address('192.0.2.5') 759 760 .. attribute:: network 761 762 The network (:class:`IPv4Network`) this interface belongs to. 763 764 >>> interface = IPv4Interface('192.0.2.5/24') 765 >>> interface.network 766 IPv4Network('192.0.2.0/24') 767 768 .. attribute:: with_prefixlen 769 770 A string representation of the interface with the mask in prefix notation. 771 772 >>> interface = IPv4Interface('192.0.2.5/24') 773 >>> interface.with_prefixlen 774 '192.0.2.5/24' 775 776 .. attribute:: with_netmask 777 778 A string representation of the interface with the network as a net mask. 779 780 >>> interface = IPv4Interface('192.0.2.5/24') 781 >>> interface.with_netmask 782 '192.0.2.5/255.255.255.0' 783 784 .. attribute:: with_hostmask 785 786 A string representation of the interface with the network as a host mask. 787 788 >>> interface = IPv4Interface('192.0.2.5/24') 789 >>> interface.with_hostmask 790 '192.0.2.5/0.0.0.255' 791 792 793 .. class:: IPv6Interface(address) 794 795 Construct an IPv6 interface. The meaning of *address* is as in the 796 constructor of :class:`IPv6Network`, except that arbitrary host addresses 797 are always accepted. 798 799 :class:`IPv6Interface` is a subclass of :class:`IPv6Address`, so it inherits 800 all the attributes from that class. In addition, the following attributes 801 are available: 802 803 .. attribute:: ip 804 .. attribute:: network 805 .. attribute:: with_prefixlen 806 .. attribute:: with_netmask 807 .. attribute:: with_hostmask 808 809 Refer to the corresponding attribute documentation in 810 :class:`IPv4Interface`. 811 812 813 Operators 814 ^^^^^^^^^ 815 816 Interface objects support some operators. Unless stated otherwise, operators 817 can only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 818 IPv6). 819 820 821 Logical operators 822 """"""""""""""""" 823 824 Interface objects can be compared with the usual set of logical operators. 825 826 For equality comparison (``==`` and ``!=``), both the IP address and network 827 must be the same for the objects to be equal. An interface will not compare 828 equal to any address or network object. 829 830 For ordering (``<``, ``>``, etc) the rules are different. Interface and 831 address objects with the same IP version can be compared, and the address 832 objects will always sort before the interface objects. Two interface objects 833 are first compared by their networks and, if those are the same, then by their 834 IP addresses. 835 836 837 Other Module Level Functions 838 ---------------------------- 839 840 The module also provides the following module level functions: 841 842 .. function:: v4_int_to_packed(address) 843 844 Represent an address as 4 packed bytes in network (big-endian) order. 845 *address* is an integer representation of an IPv4 IP address. A 846 :exc:`ValueError` is raised if the integer is negative or too large to be an 847 IPv4 IP address. 848 849 >>> ipaddress.ip_address(3221225985) 850 IPv4Address('192.0.2.1') 851 >>> ipaddress.v4_int_to_packed(3221225985) 852 b'\xc0\x00\x02\x01' 853 854 855 .. function:: v6_int_to_packed(address) 856 857 Represent an address as 16 packed bytes in network (big-endian) order. 858 *address* is an integer representation of an IPv6 IP address. A 859 :exc:`ValueError` is raised if the integer is negative or too large to be an 860 IPv6 IP address. 861 862 863 .. function:: summarize_address_range(first, last) 864 865 Return an iterator of the summarized network range given the first and last 866 IP addresses. *first* is the first :class:`IPv4Address` or 867 :class:`IPv6Address` in the range and *last* is the last :class:`IPv4Address` 868 or :class:`IPv6Address` in the range. A :exc:`TypeError` is raised if 869 *first* or *last* are not IP addresses or are not of the same version. A 870 :exc:`ValueError` is raised if *last* is not greater than *first* or if 871 *first* address version is not 4 or 6. 872 873 >>> [ipaddr for ipaddr in ipaddress.summarize_address_range( 874 ... ipaddress.IPv4Address('192.0.2.0'), 875 ... ipaddress.IPv4Address('192.0.2.130'))] 876 [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')] 877 878 879 .. function:: collapse_addresses(addresses) 880 881 Return an iterator of the collapsed :class:`IPv4Network` or 882 :class:`IPv6Network` objects. *addresses* is an iterator of 883 :class:`IPv4Network` or :class:`IPv6Network` objects. A :exc:`TypeError` is 884 raised if *addresses* contains mixed version objects. 885 886 >>> [ipaddr for ipaddr in 887 ... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'), 888 ... ipaddress.IPv4Network('192.0.2.128/25')])] 889 [IPv4Network('192.0.2.0/24')] 890 891 892 .. function:: get_mixed_type_key(obj) 893 894 Return a key suitable for sorting between networks and addresses. Address 895 and Network objects are not sortable by default; they're fundamentally 896 different, so the expression:: 897 898 IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24') 899 900 doesn't make sense. There are some times however, where you may wish to 901 have :mod:`ipaddress` sort these anyway. If you need to do this, you can use 902 this function as the *key* argument to :func:`sorted()`. 903 904 *obj* is either a network or address object. 905 906 907 Custom Exceptions 908 ----------------- 909 910 To support more specific error reporting from class constructors, the 911 module defines the following exceptions: 912 913 .. exception:: AddressValueError(ValueError) 914 915 Any value error related to the address. 916 917 918 .. exception:: NetmaskValueError(ValueError) 919 920 Any value error related to the net mask. 921
