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

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

Issue 18802: ipaddress documentation errors
Patch Set: Created 6 years, 6 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/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 276 matching lines...) Expand 10 before | Expand all | Expand 10 after
287 287
288 Address objects can be compared with the usual set of logical operators. Some 288 Address objects can be compared with the usual set of logical operators. Some
289 examples:: 289 examples::
290 290
291 >>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1') 291 >>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1')
292 True 292 True
293 >>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1') 293 >>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1')
294 False 294 False
295 >>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1') 295 >>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1')
296 True 296 True
297
298
299 Hashing
300 """""""
301
302 Address objects are hashable, so they can be used as keys in dictionaries.
297 303
298 304
299 Arithmetic operators 305 Arithmetic operators
300 """""""""""""""""""" 306 """"""""""""""""""""
301 307
302 Integers can be added to or subtracted from address objects. Some examples:: 308 Integers can be added to or subtracted from address objects. Some examples::
303 309
304 >>> IPv4Address('127.0.0.2') + 3 310 >>> IPv4Address('127.0.0.2') + 3
305 IPv4Address('127.0.0.5') 311 IPv4Address('127.0.0.5')
306 >>> IPv4Address('127.0.0.2') - 3 312 >>> IPv4Address('127.0.0.2') - 3
(...skipping 38 matching lines...) Expand 10 before | Expand all | Expand 10 after
345 so to avoid duplication they are only documented for :class:`IPv4Network`. 351 so to avoid duplication they are only documented for :class:`IPv4Network`.
346 352
347 .. class:: IPv4Network(address, strict=True) 353 .. class:: IPv4Network(address, strict=True)
348 354
349 Construct an IPv4 network definition. *address* can be one of the following: 355 Construct an IPv4 network definition. *address* can be one of the following:
350 356
351 1. A string consisting of an IP address and an optional mask, separated by 357 1. A string consisting of an IP address and an optional mask, separated by
352 a slash (``/``). The IP address is the network address, and the mask 358 a slash (``/``). The IP address is the network address, and the mask
353 can be either a single number, which means it's a *prefix*, or a string 359 can be either a single number, which means it's a *prefix*, or a string
354 representation of an IPv4 address. If it's the latter, the mask is 360 representation of an IPv4 address. If it's the latter, the mask is
355 interpreted as a *net mask* if it starts with a non-zero field, or as 361 interpreted as a *net mask* if possible, or as a *host mask* otherwise.
356 a *host mask* if it starts with a zero field. If no mask is provided, 362 If no mask is provided, it's considered to be ``/32``.
357 it's considered to be ``/32``.
358 363
359 For example, the following *address* specifications are equivalent: 364 For example, the following *address* specifications are equivalent:
360 ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and 365 ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and
361 ``192.168.1.0/0.0.0.255``. 366 ``192.168.1.0/0.0.0.255``.
362 367
368 Note that the two ambiguous cases are both treated as netmasks:
369 ``0.0.0.0/0.0.0.0`` is ``0.0.0.0/0``, and
370 ``1.2.3.4/255.255.255.255`` is ``1.2.3.4/32``.
371
363 2. An integer that fits into 32 bits. This is equivalent to a 372 2. An integer that fits into 32 bits. This is equivalent to a
364 single-address network, with the network address being *address* and 373 single-address network, with the network address being *address* and
365 the mask being ``/32``. 374 the mask being ``/32``.
366 375
367 3. An integer packed into a :class:`bytes` object of length 4, big-endian. 376 3. An integer packed into a :class:`bytes` object of length 4, big-endian.
368 The interpretation is similar to an integer *address*. 377 The interpretation is similar to an integer *address*.
369 378
370 An :exc:`AddressValueError` is raised if *address* is not a valid IPv4 379 An :exc:`AddressValueError` is raised if *address* is not a valid IPv4
371 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for 380 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for
372 an IPv4 address. 381 an IPv4 address.
(...skipping 25 matching lines...) Expand all
398 .. attribute:: network_address 407 .. attribute:: network_address
399 408
400 The network address for the network. The network address and the 409 The network address for the network. The network address and the
401 prefix length together uniquely define a network. 410 prefix length together uniquely define a network.
402 411
403 .. attribute:: broadcast_address 412 .. attribute:: broadcast_address
404 413
405 The broadcast address for the network. Packets sent to the broadcast 414 The broadcast address for the network. Packets sent to the broadcast
406 address should be received by every host on the network. 415 address should be received by every host on the network.
407 416
408 .. attribute:: host mask 417 .. attribute:: netmask
409 418
410 The host mask, as a string. 419 The netmask, as an :class:`IPv4Address` object.
420
421 .. attribute:: hostmask
422
423 The host mask, as an :class:`IPv4Address` object.
411 424
412 .. attribute:: with_prefixlen 425 .. attribute:: with_prefixlen
413 .. attribute:: compressed 426 .. attribute:: compressed
414 .. attribute:: exploded 427 .. attribute:: exploded
415 428
416 A string representation of the network, with the mask in prefix 429 A string representation of the network, with the mask in prefix
417 notation. 430 notation.
418 431
419 ``with_prefixlen`` and ``compressed`` are always the same as 432 ``with_prefixlen`` and ``compressed`` are always the same as
420 ``str(network)``. 433 ``str(network)``.
(...skipping 98 matching lines...) Expand 10 before | Expand all | Expand 10 after
519 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/3 2')) 532 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/3 2'))
520 1 533 1
521 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/3 2')) 534 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/3 2'))
522 0 535 0
523 536
524 537
525 .. class:: IPv6Network(address, strict=True) 538 .. class:: IPv6Network(address, strict=True)
526 539
527 Construct an IPv6 network definition. *address* can be one of the following: 540 Construct an IPv6 network definition. *address* can be one of the following:
528 541
529 1. A string consisting of an IP address and an optional mask, separated by 542 1. A string consisting of an IP address and an optional prefix length,
530 a slash (``/``). The IP address is the network address, and the mask 543 separated by a slash (``/``). The IP address is the network address,
531 can be either a single number, which means it's a *prefix*, or a string 544 and the prefix length must be a single number, the *prefix*. If no
532 representation of an IPv6 address. If it's the latter, the mask is 545 prefix length is provided, it's considered to be ``/128``.
533 interpreted as a *net mask*. If no mask is provided, it's considered to
534 be ``/128``.
535 546
536 For example, the following *address* specifications are equivalent: 547 For example, the *address* specification might be ``2001:db00::0/24``.
537 ``2001:db00::0/24`` and ``2001:db00::0/ffff:ff00::``. 548
549 Note that IPv6 networks can't be specified using a net mask or a host
550 mask - those features are only in :class:`IPv4Network`.
538 551
539 2. An integer that fits into 128 bits. This is equivalent to a 552 2. An integer that fits into 128 bits. This is equivalent to a
540 single-address network, with the network address being *address* and 553 single-address network, with the network address being *address* and
541 the mask being ``/128``. 554 the mask being ``/128``.
542 555
543 3. An integer packed into a :class:`bytes` object of length 16, bit-endian. 556 3. An integer packed into a :class:`bytes` object of length 16, bit-endian.
544 The interpretation is similar to an integer *address*. 557 The interpretation is similar to an integer *address*.
545 558
546 An :exc:`AddressValueError` is raised if *address* is not a valid IPv6 559 An :exc:`AddressValueError` is raised if *address* is not a valid IPv6
547 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for 560 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for
548 an IPv6 address. 561 an IPv6 address.
549 562
550 If *strict* is ``True`` and host bits are set in the supplied address, 563 If *strict* is ``True`` and host bits are set in the supplied address,
551 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out 564 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out
552 to determine the appropriate network address. 565 to determine the appropriate network address.
553 566
554 .. attribute:: version 567 .. attribute:: version
555 .. attribute:: max_prefixlen 568 .. attribute:: max_prefixlen
556 .. attribute:: is_multicast 569 .. attribute:: is_multicast
557 .. attribute:: is_private 570 .. attribute:: is_private
558 .. attribute:: is_unspecified 571 .. attribute:: is_unspecified
559 .. attribute:: is_reserved 572 .. attribute:: is_reserved
560 .. attribute:: is_loopback 573 .. attribute:: is_loopback
561 .. attribute:: is_link_local 574 .. attribute:: is_link_local
562 .. attribute:: network_address 575 .. attribute:: network_address
563 .. attribute:: broadcast_address 576 .. attribute:: broadcast_address
564 .. attribute:: host mask 577 .. attribute:: netmask
578 .. attribute:: hostmask
565 .. attribute:: with_prefixlen 579 .. attribute:: with_prefixlen
566 .. attribute:: compressed 580 .. attribute:: compressed
567 .. attribute:: exploded 581 .. attribute:: exploded
568 .. attribute:: with_netmask 582 .. attribute:: with_netmask
569 .. attribute:: with_hostmask 583 .. attribute:: with_hostmask
570 .. attribute:: num_addresses 584 .. attribute:: num_addresses
571 .. attribute:: prefixlen 585 .. attribute:: prefixlen
572 .. method:: hosts() 586 .. method:: hosts()
573 .. method:: overlaps(other) 587 .. method:: overlaps(other)
574 .. method:: address_exclude(network) 588 .. method:: address_exclude(network)
(...skipping 14 matching lines...) Expand all
589 ^^^^^^^^^ 603 ^^^^^^^^^
590 604
591 Network objects support some operators. Unless stated otherwise, operators can 605 Network objects support some operators. Unless stated otherwise, operators can
592 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 606 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
593 IPv6). 607 IPv6).
594 608
595 609
596 Logical operators 610 Logical operators
597 """"""""""""""""" 611 """""""""""""""""
598 612
599 Network objects can be compared with the usual set of logical operators, 613 Network objects can be compared with the usual set of logical operators.
600 similarly to address objects. 614 Network objects are ordered first by network address, then by net mask.
615
616
617 Hashing
618 """""""
619
620 Network objects are hashable, so they can be used as keys in dictionaries.
601 621
602 622
603 Iteration 623 Iteration
604 """"""""" 624 """""""""
605 625
606 Network objects can be iterated to list all the addresses belonging to the 626 Network objects can be iterated to list all the addresses belonging to the
607 network. For iteration, *all* hosts are returned, including unusable hosts 627 network. For iteration, *all* hosts are returned, including unusable hosts
608 (for usable hosts, use the :meth:`~IPv4Network.hosts` method). An 628 (for usable hosts, use the :meth:`~IPv4Network.hosts` method). An
609 example:: 629 example::
610 630
(...skipping 98 matching lines...) Expand 10 before | Expand all | Expand 10 after
709 are available: 729 are available:
710 730
711 .. attribute:: ip 731 .. attribute:: ip
712 .. attribute:: network 732 .. attribute:: network
713 .. attribute:: with_prefixlen 733 .. attribute:: with_prefixlen
714 .. attribute:: with_netmask 734 .. attribute:: with_netmask
715 .. attribute:: with_hostmask 735 .. attribute:: with_hostmask
716 736
717 Refer to the corresponding attribute documentation in 737 Refer to the corresponding attribute documentation in
718 :class:`IPv4Interface`. 738 :class:`IPv4Interface`.
739
740
741 Operators
742 ^^^^^^^^^
743
744 Interface objects support some operators. Unless stated otherwise, operators ca n
745 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
746 IPv6).
747
748
749 Logical operators
750 """""""""""""""""
751
752 Interface objects can be compared with the usual set of logical operators.
753
754 For equality comparison (``==`` and ``!=``), both the IP address and network mus t
755 be the same for the objects to be equal. An Interface will not compare equal to
756 any Address or Network object.
757
758 For ordering (``<``, ``>``, etc) the rules are different.
759 Interface and address objects with the same IP version can be compared, and the
760 address objects will always sort before the interface objects. Two interface
ezio.melotti 2013/08/23 22:21:22 There's an extra space here. Also a couple of line
761 objects are compared by comparing their networks, using the same rules as
762 :class:`IPv4Network` or :class:`IPv6Network`. The IP address plays no part in
763 the comparison. Note that you will get strange results when comparing two
ezio.melotti 2013/08/23 22:21:22 "getting strange results" doesn't sound appropriat
764 interface objects with the same network but different IP addresses. E.g.::
765
766 >>> import ipaddress
767 >>> a = ipaddress.IPv4Interface('128.0.0.3/8')
768 >>> b = ipaddress.IPv4Interface('128.0.0.5/8')
769 >>> a < b
770 False
771 >>> b < a
772 False
773 >>> a > b
774 True
775 >>> b > a
776 True
777
778 Also, note that since the comparison rules for interfaces are different from the
779 rules for addresses, this means that :class:`IPv4Interface` and its base class
780 :class:`IPv4Address` don't follow the Liskov Substitution Principle. I.e. you
ezio.melotti 2013/08/23 22:21:22 I'm not sure it's necessary to mention the LSP. A
781 can't pass a :class:`IPv4Interface` to code that expects a :class:`IPv4Address`
782 and uses comparison operators or hashing. Similarly for :class:`IPv6Interface`
783 and :class:`IPv6Address`.
784
785
786 Hashing
787 """""""
788
789 Interface objects are hashable, so they can be used as keys in dictionaries.
719 790
720 791
721 Other Module Level Functions 792 Other Module Level Functions
722 ---------------------------- 793 ----------------------------
723 794
724 The module also provides the following module level functions: 795 The module also provides the following module level functions:
725 796
726 .. function:: v4_int_to_packed(address) 797 .. function:: v4_int_to_packed(address)
727 798
728 Represent an address as 4 packed bytes in network (big-endian) order. 799 Represent an address as 4 packed bytes in network (big-endian) order.
(...skipping 66 matching lines...) Expand 10 before | Expand all | Expand 10 after
795 module defines the following exceptions: 866 module defines the following exceptions:
796 867
797 .. exception:: AddressValueError(ValueError) 868 .. exception:: AddressValueError(ValueError)
798 869
799 Any value error related to the address. 870 Any value error related to the address.
800 871
801 872
802 .. exception:: NetmaskValueError(ValueError) 873 .. exception:: NetmaskValueError(ValueError)
803 874
804 Any value error related to the netmask. 875 Any value error related to the netmask.
OLDNEW
« no previous file with comments | « no previous file | Lib/ipaddress.py » ('j') | no next file with comments »

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