Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(6)

Side by Side Diff: Doc/library/ipaddress.rst

Issue 18802: ipaddress documentation errors
Patch Set: Created 3 years, 8 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | Lib/test/test_ipaddress.py » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`ipaddress` --- IPv4/IPv6 manipulation library 1 :mod:`ipaddress` --- IPv4/IPv6 manipulation library
2 =================================================== 2 ===================================================
3 3
4 .. module:: ipaddress 4 .. module:: ipaddress
5 :synopsis: IPv4/IPv6 manipulation library. 5 :synopsis: IPv4/IPv6 manipulation library.
6 .. moduleauthor:: Peter Moody 6 .. moduleauthor:: Peter Moody
7 7
8 **Source code:** :source:`Lib/ipaddress.py` 8 **Source code:** :source:`Lib/ipaddress.py`
9 9
10 -------------- 10 --------------
(...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after
84 84
85 IP Addresses 85 IP Addresses
86 ------------ 86 ------------
87 87
88 Address objects 88 Address objects
89 ^^^^^^^^^^^^^^^ 89 ^^^^^^^^^^^^^^^
90 90
91 The :class:`IPv4Address` and :class:`IPv6Address` objects share a lot of common 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 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 93 also implemented by :class:`IPv4Address` objects, in order to make it easier to
94 write code that handles both IP versions correctly. 94 write code that handles both IP versions correctly. Address objects are
95 hashable, so they can be used as keys in dictionaries.
95 96
96 .. class:: IPv4Address(address) 97 .. class:: IPv4Address(address)
97 98
98 Construct an IPv4 address. An :exc:`AddressValueError` is raised if 99 Construct an IPv4 address. An :exc:`AddressValueError` is raised if
99 *address* is not a valid IPv4 address. 100 *address* is not a valid IPv4 address.
100 101
101 The following constitutes a valid IPv4 address: 102 The following constitutes a valid IPv4 address:
102 103
103 1. A string in decimal-dot notation, consisting of four decimal integers in 104 1. A string in decimal-dot notation, consisting of four decimal integers in
104 the inclusive range 0-255, separated by dots (e.g. ``192.168.0.1``). Each 105 the inclusive range 0-255, separated by dots (e.g. ``192.168.0.1``). Each
(...skipping 124 matching lines...) Expand 10 before | Expand all | Expand 10 after
229 zeroes collapsed to a single empty group. 230 zeroes collapsed to a single empty group.
230 231
231 This is also the value returned by ``str(addr)`` for IPv6 addresses. 232 This is also the value returned by ``str(addr)`` for IPv6 addresses.
232 233
233 .. attribute:: exploded 234 .. attribute:: exploded
234 235
235 The long form of the address representation, with all leading zeroes and 236 The long form of the address representation, with all leading zeroes and
236 groups consisting entirely of zeroes included. 237 groups consisting entirely of zeroes included.
237 238
238 239
239 For the following attributes, see the corresponding documention of the 240 For the following attributes, see the corresponding documentation of the
240 :class:`IPv4Address` class: 241 :class:`IPv4Address` class:
241 242
242 .. attribute:: packed 243 .. attribute:: packed
243 .. attribute:: reverse_pointer 244 .. attribute:: reverse_pointer
244 .. attribute:: version 245 .. attribute:: version
245 .. attribute:: max_prefixlen 246 .. attribute:: max_prefixlen
246 .. attribute:: is_multicast 247 .. attribute:: is_multicast
247 .. attribute:: is_private 248 .. attribute:: is_private
248 .. attribute:: is_global 249 .. attribute:: is_global
249 .. attribute:: is_unspecified 250 .. attribute:: is_unspecified
(...skipping 111 matching lines...) Expand 10 before | Expand all | Expand 10 after
361 host mask equivalent to ``/24`` in IPv4 is ``0.0.0.255``. 362 host mask equivalent to ``/24`` in IPv4 is ``0.0.0.255``.
362 363
363 364
364 Network objects 365 Network objects
365 ^^^^^^^^^^^^^^^ 366 ^^^^^^^^^^^^^^^
366 367
367 All attributes implemented by address objects are implemented by network 368 All attributes implemented by address objects are implemented by network
368 objects as well. In addition, network objects implement additional attributes. 369 objects as well. In addition, network objects implement additional attributes.
369 All of these are common between :class:`IPv4Network` and :class:`IPv6Network`, 370 All of these are common between :class:`IPv4Network` and :class:`IPv6Network`,
370 so to avoid duplication they are only documented for :class:`IPv4Network`. 371 so to avoid duplication they are only documented for :class:`IPv4Network`.
372 Network objects are hashable, so they can be used as keys in dictionaries.
371 373
372 .. class:: IPv4Network(address, strict=True) 374 .. class:: IPv4Network(address, strict=True)
373 375
374 Construct an IPv4 network definition. *address* can be one of the following: 376 Construct an IPv4 network definition. *address* can be one of the following:
375 377
376 1. A string consisting of an IP address and an optional mask, separated by 378 1. A string consisting of an IP address and an optional mask, separated by
377 a slash (``/``). The IP address is the network address, and the mask 379 a slash (``/``). The IP address is the network address, and the mask
378 can be either a single number, which means it's a *prefix*, or a string 380 can be either a single number, which means it's a *prefix*, or a string
379 representation of an IPv4 address. If it's the latter, the mask is 381 representation of an IPv4 address. If it's the latter, the mask is
380 interpreted as a *net mask* if it starts with a non-zero field, or as 382 interpreted as a *net mask* if possible, or as a *host mask* otherwise.
381 a *host mask* if it starts with a zero field. If no mask is provided, 383 If no mask is provided, it's considered to be ``/32``.
382 it's considered to be ``/32``.
383 384
384 For example, the following *address* specifications are equivalent: 385 For example, the following *address* specifications are equivalent:
385 ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and 386 ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and
386 ``192.168.1.0/0.0.0.255``. 387 ``192.168.1.0/0.0.0.255``.
388
389 Note that the two ambiguous cases are both treated as net masks:
390 ``0.0.0.0/0.0.0.0`` is ``0.0.0.0/0``, and
391 ``1.2.3.4/255.255.255.255`` is ``1.2.3.4/32``.
387 392
388 2. An integer that fits into 32 bits. This is equivalent to a 393 2. An integer that fits into 32 bits. This is equivalent to a
389 single-address network, with the network address being *address* and 394 single-address network, with the network address being *address* and
390 the mask being ``/32``. 395 the mask being ``/32``.
391 396
392 3. An integer packed into a :class:`bytes` object of length 4, big-endian. 397 3. An integer packed into a :class:`bytes` object of length 4, big-endian.
393 The interpretation is similar to an integer *address*. 398 The interpretation is similar to an integer *address*.
394 399
395 4. A two-tuple of an address description and a netmask, where the address 400 4. A two-tuple of an address description and a netmask, where the address
396 description is either a string, a 32-bits integer, a 4-bytes packed 401 description is either a string, a 32-bits integer, a 4-bytes packed
397 integer, or an existing IPv4Address object; and the netmask is either 402 integer, or an existing IPv4Address object; and the netmask is either
398 an integer representing the prefix length (e.g. ``24``) or a string 403 an integer representing the prefix length (e.g. ``24``) or a string
399 representing the prefix mask (e.g. ``255.255.255.0``). 404 representing the prefix mask (e.g. ``255.255.255.0``).
400 405
401 An :exc:`AddressValueError` is raised if *address* is not a valid IPv4 406 An :exc:`AddressValueError` is raised if *address* is not a valid IPv4
402 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for 407 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for
403 an IPv4 address. 408 an IPv4 address.
404 409
405 If *strict* is ``True`` and host bits are set in the supplied address, 410 If *strict* is ``True`` and host bits are set in the supplied address,
406 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out 411 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out
407 to determine the appropriate network address. 412 to determine the appropriate network address.
408 413
409 Unless stated otherwise, all network methods accepting other network/address 414 Unless stated otherwise, all network methods accepting other network/address
410 objects will raise :exc:`TypeError` if the argument's IP version is 415 objects will raise :exc:`TypeError` if the argument's IP version is
411 incompatible to ``self`` 416 incompatible to ``self``.
412 417
413 .. versionchanged:: 3.5 418 .. versionchanged:: 3.5
414 419
415 Added the two-tuple form for the *address* constructor parameter. 420 Added the two-tuple form for the *address* constructor parameter.
416 421
417 .. attribute:: version 422 .. attribute:: version
418 .. attribute:: max_prefixlen 423 .. attribute:: max_prefixlen
419 424
420 Refer to the corresponding attribute documentation in 425 Refer to the corresponding attribute documentation in
421 :class:`IPv4Address` 426 :class:`IPv4Address`.
422 427
423 .. attribute:: is_multicast 428 .. attribute:: is_multicast
424 .. attribute:: is_private 429 .. attribute:: is_private
425 .. attribute:: is_unspecified 430 .. attribute:: is_unspecified
426 .. attribute:: is_reserved 431 .. attribute:: is_reserved
427 .. attribute:: is_loopback 432 .. attribute:: is_loopback
428 .. attribute:: is_link_local 433 .. attribute:: is_link_local
429 434
430 These attributes are true for the network as a whole if they are true 435 These attributes are true for the network as a whole if they are true
431 for both the network address and the broadcast address 436 for both the network address and the broadcast address.
432 437
433 .. attribute:: network_address 438 .. attribute:: network_address
434 439
435 The network address for the network. The network address and the 440 The network address for the network. The network address and the
436 prefix length together uniquely define a network. 441 prefix length together uniquely define a network.
437 442
438 .. attribute:: broadcast_address 443 .. attribute:: broadcast_address
439 444
440 The broadcast address for the network. Packets sent to the broadcast 445 The broadcast address for the network. Packets sent to the broadcast
441 address should be received by every host on the network. 446 address should be received by every host on the network.
442 447
443 .. attribute:: hostmask 448 .. attribute:: hostmask
444 449
445 The host mask, as a string. 450 The host mask, as an :class:`IPv4Address` object.
451
452 .. attribute:: netmask
453
454 The net mask, as an :class:`IPv4Address` object.
446 455
447 .. attribute:: with_prefixlen 456 .. attribute:: with_prefixlen
448 .. attribute:: compressed 457 .. attribute:: compressed
449 .. attribute:: exploded 458 .. attribute:: exploded
450 459
451 A string representation of the network, with the mask in prefix 460 A string representation of the network, with the mask in prefix
452 notation. 461 notation.
453 462
454 ``with_prefixlen`` and ``compressed`` are always the same as 463 ``with_prefixlen`` and ``compressed`` are always the same as
455 ``str(network)``. 464 ``str(network)``.
(...skipping 98 matching lines...) Expand 10 before | Expand all | Expand 10 after
554 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/3 2')) 563 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/3 2'))
555 1 564 1
556 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/3 2')) 565 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/3 2'))
557 0 566 0
558 567
559 568
560 .. class:: IPv6Network(address, strict=True) 569 .. class:: IPv6Network(address, strict=True)
561 570
562 Construct an IPv6 network definition. *address* can be one of the following: 571 Construct an IPv6 network definition. *address* can be one of the following:
563 572
564 1. A string consisting of an IP address and an optional mask, separated by 573 1. A string consisting of an IP address and an optional prefix length,
565 a slash (``/``). The IP address is the network address, and the mask 574 separated by a slash (``/``). The IP address is the network address,
566 can be either a single number, which means it's a *prefix*, or a string 575 and the prefix length must be a single number, the *prefix*. If no
567 representation of an IPv6 address. If it's the latter, the mask is 576 prefix length is provided, it's considered to be ``/128``.
568 interpreted as a *net mask*. If no mask is provided, it's considered to
569 be ``/128``.
570 577
571 For example, the following *address* specifications are equivalent: 578 For example, the *address* specification might be ``2001:db00::0/24``.
572 ``2001:db00::0/24`` and ``2001:db00::0/ffff:ff00::``. 579
580 Note that IPv6 networks can't be specified using a net mask or a host
581 mask - those features are only in :class:`IPv4Network`.
573 582
574 2. An integer that fits into 128 bits. This is equivalent to a 583 2. An integer that fits into 128 bits. This is equivalent to a
575 single-address network, with the network address being *address* and 584 single-address network, with the network address being *address* and
576 the mask being ``/128``. 585 the mask being ``/128``.
577 586
578 3. An integer packed into a :class:`bytes` object of length 16, big-endian. 587 3. An integer packed into a :class:`bytes` object of length 16, big-endian.
579 The interpretation is similar to an integer *address*. 588 The interpretation is similar to an integer *address*.
580 589
581 4. A two-tuple of an address description and a netmask, where the address 590 4. A two-tuple of an address description and a netmask, where the address
582 description is either a string, a 128-bits integer, a 16-bytes packed 591 description is either a string, a 128-bits integer, a 16-bytes packed
(...skipping 16 matching lines...) Expand all
599 .. attribute:: max_prefixlen 608 .. attribute:: max_prefixlen
600 .. attribute:: is_multicast 609 .. attribute:: is_multicast
601 .. attribute:: is_private 610 .. attribute:: is_private
602 .. attribute:: is_unspecified 611 .. attribute:: is_unspecified
603 .. attribute:: is_reserved 612 .. attribute:: is_reserved
604 .. attribute:: is_loopback 613 .. attribute:: is_loopback
605 .. attribute:: is_link_local 614 .. attribute:: is_link_local
606 .. attribute:: network_address 615 .. attribute:: network_address
607 .. attribute:: broadcast_address 616 .. attribute:: broadcast_address
608 .. attribute:: hostmask 617 .. attribute:: hostmask
618 .. attribute:: netmask
609 .. attribute:: with_prefixlen 619 .. attribute:: with_prefixlen
610 .. attribute:: compressed 620 .. attribute:: compressed
611 .. attribute:: exploded 621 .. attribute:: exploded
612 .. attribute:: with_netmask 622 .. attribute:: with_netmask
613 .. attribute:: with_hostmask 623 .. attribute:: with_hostmask
614 .. attribute:: num_addresses 624 .. attribute:: num_addresses
615 .. attribute:: prefixlen 625 .. attribute:: prefixlen
616 .. method:: hosts() 626 .. method:: hosts()
617 .. method:: overlaps(other) 627 .. method:: overlaps(other)
618 .. method:: address_exclude(network) 628 .. method:: address_exclude(network)
619 .. method:: subnets(prefixlen_diff=1, new_prefix=None) 629 .. method:: subnets(prefixlen_diff=1, new_prefix=None)
620 .. method:: supernet(prefixlen_diff=1, new_prefix=None) 630 .. method:: supernet(prefixlen_diff=1, new_prefix=None)
621 .. method:: compare_networks(other) 631 .. method:: compare_networks(other)
622 632
623 Refer to the corresponding attribute documentation in 633 Refer to the corresponding attribute documentation in
624 :class:`IPv4Network` 634 :class:`IPv4Network`.
625 635
626 .. attribute:: is_site_local 636 .. attribute:: is_site_local
627 637
628 These attribute is true for the network as a whole if it is true 638 These attribute is true for the network as a whole if it is true
629 for both the network address and the broadcast address 639 for both the network address and the broadcast address.
630 640
631 641
632 Operators 642 Operators
633 ^^^^^^^^^ 643 ^^^^^^^^^
634 644
635 Network objects support some operators. Unless stated otherwise, operators can 645 Network objects support some operators. Unless stated otherwise, operators can
636 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 646 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
637 IPv6). 647 IPv6).
638 648
639 649
640 Logical operators 650 Logical operators
641 """"""""""""""""" 651 """""""""""""""""
642 652
643 Network objects can be compared with the usual set of logical operators, 653 Network objects can be compared with the usual set of logical operators.
644 similarly to address objects. 654 Network objects are ordered first by network address, then by net mask.
645 655
646 656
647 Iteration 657 Iteration
648 """"""""" 658 """""""""
649 659
650 Network objects can be iterated to list all the addresses belonging to the 660 Network objects can be iterated to list all the addresses belonging to the
651 network. For iteration, *all* hosts are returned, including unusable hosts 661 network. For iteration, *all* hosts are returned, including unusable hosts
652 (for usable hosts, use the :meth:`~IPv4Network.hosts` method). An 662 (for usable hosts, use the :meth:`~IPv4Network.hosts` method). An
653 example:: 663 example::
654 664
(...skipping 28 matching lines...) Expand all
683 >>> IPv4Network('192.0.2.0/28')[15] 693 >>> IPv4Network('192.0.2.0/28')[15]
684 IPv4Address('192.0.2.15') 694 IPv4Address('192.0.2.15')
685 >>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28') 695 >>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28')
686 True 696 True
687 >>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28') 697 >>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28')
688 False 698 False
689 699
690 700
691 Interface objects 701 Interface objects
692 ----------------- 702 -----------------
703
704 Interface objects are hashable, so they can be used as keys in dictionaries.
693 705
694 .. class:: IPv4Interface(address) 706 .. class:: IPv4Interface(address)
695 707
696 Construct an IPv4 interface. The meaning of *address* is as in the 708 Construct an IPv4 interface. The meaning of *address* is as in the
697 constructor of :class:`IPv4Network`, except that arbitrary host addresses 709 constructor of :class:`IPv4Network`, except that arbitrary host addresses
698 are always accepted. 710 are always accepted.
699 711
700 :class:`IPv4Interface` is a subclass of :class:`IPv4Address`, so it inherits 712 :class:`IPv4Interface` is a subclass of :class:`IPv4Address`, so it inherits
701 all the attributes from that class. In addition, the following attributes 713 all the attributes from that class. In addition, the following attributes
702 are available: 714 are available:
(...skipping 50 matching lines...) Expand 10 before | Expand all | Expand 10 after
753 are available: 765 are available:
754 766
755 .. attribute:: ip 767 .. attribute:: ip
756 .. attribute:: network 768 .. attribute:: network
757 .. attribute:: with_prefixlen 769 .. attribute:: with_prefixlen
758 .. attribute:: with_netmask 770 .. attribute:: with_netmask
759 .. attribute:: with_hostmask 771 .. attribute:: with_hostmask
760 772
761 Refer to the corresponding attribute documentation in 773 Refer to the corresponding attribute documentation in
762 :class:`IPv4Interface`. 774 :class:`IPv4Interface`.
775
776
777 Operators
778 ^^^^^^^^^
779
780 Interface objects support some operators. Unless stated otherwise, operators
781 can only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
782 IPv6).
783
784
785 Logical operators
786 """""""""""""""""
787
788 Interface objects can be compared with the usual set of logical operators.
789
790 For equality comparison (``==`` and ``!=``), both the IP address and network
791 must be the same for the objects to be equal. An interface will not compare
792 equal to any address or network object.
793
794 For ordering (``<``, ``>``, etc) the rules are different. Interface and
795 address objects with the same IP version can be compared, and the address
796 objects will always sort before the interface objects. Two interface objects
797 are compared by comparing their networks, using the same rules as
798 :class:`IPv4Network` or :class:`IPv6Network`. The IP address plays no part in
799 the comparison. Note that you will get strange results when comparing two
800 interface objects with the same network but different IP addresses::
801
802 >>> a = ipaddress.IPv4Interface('128.0.0.3/8')
803 >>> b = ipaddress.IPv4Interface('128.0.0.5/8')
804 >>> a < b
805 False
806 >>> b < a
807 False
808 >>> a > b
809 True
810 >>> b > a
811 True
763 812
764 813
765 Other Module Level Functions 814 Other Module Level Functions
766 ---------------------------- 815 ----------------------------
767 816
768 The module also provides the following module level functions: 817 The module also provides the following module level functions:
769 818
770 .. function:: v4_int_to_packed(address) 819 .. function:: v4_int_to_packed(address)
771 820
772 Represent an address as 4 packed bytes in network (big-endian) order. 821 Represent an address as 4 packed bytes in network (big-endian) order.
(...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after
820 .. function:: get_mixed_type_key(obj) 869 .. function:: get_mixed_type_key(obj)
821 870
822 Return a key suitable for sorting between networks and addresses. Address 871 Return a key suitable for sorting between networks and addresses. Address
823 and Network objects are not sortable by default; they're fundamentally 872 and Network objects are not sortable by default; they're fundamentally
824 different, so the expression:: 873 different, so the expression::
825 874
826 IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24') 875 IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')
827 876
828 doesn't make sense. There are some times however, where you may wish to 877 doesn't make sense. There are some times however, where you may wish to
829 have :mod:`ipaddress` sort these anyway. If you need to do this, you can use 878 have :mod:`ipaddress` sort these anyway. If you need to do this, you can use
830 this function as the ``key`` argument to :func:`sorted()`. 879 this function as the *key* argument to :func:`sorted()`.
831 880
832 *obj* is either a network or address object. 881 *obj* is either a network or address object.
833 882
834 883
835 Custom Exceptions 884 Custom Exceptions
836 ----------------- 885 -----------------
837 886
838 To support more specific error reporting from class constructors, the 887 To support more specific error reporting from class constructors, the
839 module defines the following exceptions: 888 module defines the following exceptions:
840 889
841 .. exception:: AddressValueError(ValueError) 890 .. exception:: AddressValueError(ValueError)
842 891
843 Any value error related to the address. 892 Any value error related to the address.
844 893
845 894
846 .. exception:: NetmaskValueError(ValueError) 895 .. exception:: NetmaskValueError(ValueError)
847 896
848 Any value error related to the netmask. 897 Any value error related to the net mask.
OLDNEW
« no previous file with comments | « no previous file | Lib/test/test_ipaddress.py » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+