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