bpo-18802: Add more details to ipaddress documentation (GH-6083) · python/cpython@a323eee (original) (raw)

`@@ -91,7 +91,8 @@ Address objects

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.

94

write code that handles both IP versions correctly. Address objects are

95

`` +

:term:hashable, so they can be used as keys in dictionaries.

95

96

97

`.. class:: IPv4Address(address)

97

98

`@@ -368,6 +369,8 @@ All attributes implemented by address objects are implemented by network

368

369

`objects as well. In addition, network objects implement additional attributes.

369

370

`` All of these are common between :class:IPv4Network and :class:IPv6Network,

370

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.

371

374

372

375

`.. class:: IPv4Network(address, strict=True)

373

376

`` @@ -377,8 +380,9 @@ so to avoid duplication they are only documented for :class:IPv4Network.

377

380

``` a slash (/). The IP address is the network address, and the mask


`378`

`381`

` can be either a single number, which means it's a *prefix*, or a string

`

`379`

`382`

` 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

`

`381`

``

`-

a *host mask* if it starts with a zero field. If no mask is provided,

`

``

`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,

`

`382`

`386`

```  it's considered to be ``/32``.

383

387

384

388

` For example, the following address specifications are equivalent:

`` @@ -408,7 +412,7 @@ so to avoid duplication they are only documented for :class:IPv4Network.

408

412

409

413

` Unless stated otherwise, all network methods accepting other network/address

410

414

`` objects will raise :exc:TypeError if the argument's IP version is

411


 incompatible to ``self``

415


 incompatible to ``self``.

412

416

413

417

` .. versionchanged:: 3.5

414

418

`` @@ -418,7 +422,7 @@ so to avoid duplication they are only documented for :class:IPv4Network.

418

422

` .. attribute:: max_prefixlen

419

423

420

424

` Refer to the corresponding attribute documentation in

421

`` -

:class:IPv4Address

425

`` +

:class:IPv4Address.

422

426

423

427

` .. attribute:: is_multicast

424

428

` .. attribute:: is_private

`` @@ -428,7 +432,7 @@ so to avoid duplication they are only documented for :class:IPv4Network.

428

432

` .. attribute:: is_link_local

429

433

430

434

` These attributes are true for the network as a whole if they are true

431

for both the network address and the broadcast address

435

for both the network address and the broadcast address.

432

436

433

437

` .. attribute:: network_address

434

438

`` @@ -590,10 +594,10 @@ so to avoid duplication they are only documented for :class:IPv4Network.

590

594

591

595

` Construct an IPv6 network definition. address can be one of the following:

592

596

593

A string consisting of an IP address and an optional mask, separated by

594


 a slash (``/``). The IP address is the network address, and the mask

595

is a single number, which represents a prefix. If no mask is provided,

596


 it's considered to be ``/128``.

597

A string consisting of an IP address and an optional prefix length,

598


separated by a slash (``/``). The IP address is the network address,

599

and the prefix length must be a single number, the prefix. If no

600


prefix length is provided, it's considered to be ``/128``.

597

601

598

602

` Note that currently expanded netmasks are not supported. That means

599

603

``` 2001:db00::0/24 is a valid argument while 2001:db00::0/ffff:ff00::


`` @@ -652,12 +656,12 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.

``

`652`

`656`

` .. method:: compare_networks(other)

`

`653`

`657`

``

`654`

`658`

` Refer to the corresponding attribute documentation in

`

`655`

``

`` -

:class:`IPv4Network`

``

``

`659`

`` +

:class:`IPv4Network`.

``

`656`

`660`

``

`657`

`661`

` .. attribute:: is_site_local

`

`658`

`662`

``

`659`

`663`

` These attribute is true for the network as a whole if it is true

`

`660`

``

`-

for both the network address and the broadcast address

`

``

`664`

`+

for both the network address and the broadcast address.

`

`661`

`665`

``

`662`

`666`

``

`663`

`667`

`Operators

`

`@@ -671,8 +675,8 @@ IPv6).

`

`671`

`675`

`Logical operators

`

`672`

`676`

`"""""""""""""""""

`

`673`

`677`

``

`674`

``

`-

Network objects can be compared with the usual set of logical operators,

`

`675`

``

`-

similarly to address objects.

`

``

`678`

`+

Network objects can be compared with the usual set of logical operators.

`

``

`679`

`+

Network objects are ordered first by network address, then by net mask.

`

`676`

`680`

``

`677`

`681`

``

`678`

`682`

`Iteration

`

`@@ -722,6 +726,9 @@ Network objects can act as containers of addresses. Some examples::

`

`722`

`726`

`Interface objects

`

`723`

`727`

`-----------------

`

`724`

`728`

``

``

`729`

`` +

Interface objects are :term:`hashable`, so they can be used as keys in

``

``

`730`

`+

dictionaries.

`

``

`731`

`+`

`725`

`732`

`.. class:: IPv4Interface(address)

`

`726`

`733`

``

`727`

`734`

` Construct an IPv4 interface. The meaning of *address* is as in the

`

`@@ -793,6 +800,30 @@ Interface objects

`

`793`

`800`

`` :class:`IPv4Interface`.

``

`794`

`801`

``

`795`

`802`

``

``

`803`

`+

Operators

`

``

`804`

`+

^^^^^^^^^

`

``

`805`

`+`

``

`806`

`+

Interface objects support some operators. Unless stated otherwise, operators

`

``

`807`

`+

can only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with

`

``

`808`

`+

IPv6).

`

``

`809`

`+`

``

`810`

`+`

``

`811`

`+

Logical operators

`

``

`812`

`+

"""""""""""""""""

`

``

`813`

`+`

``

`814`

`+

Interface objects can be compared with the usual set of logical operators.

`

``

`815`

`+`

``

`816`

``` +

For equality comparison (``==`` and ``!=``), both the IP address and network

817

must be the same for the objects to be equal. An interface will not compare

818

equal to any address or network object.

819

+

820


For ordering (``<``, ``>``, etc) the rules are different. Interface and

821

address objects with the same IP version can be compared, and the address

822

objects will always sort before the interface objects. Two interface objects

823

are first compared by their networks and, if those are the same, then by their

824

IP addresses.

825

+

826

+

796

827

`Other Module Level Functions

797

828

`----------------------------

798

829

`@@ -858,7 +889,7 @@ The module also provides the following module level functions:

858

889

859

890

` doesn't make sense. There are some times however, where you may wish to

860

891

`` have :mod:ipaddress sort these anyway. If you need to do this, you can use

861


 this function as the ``key`` argument to :func:`sorted()`.

892

`` +

this function as the key argument to :func:sorted().

862

893

863

894

` obj is either a network or address object.

864

895

`@@ -876,4 +907,4 @@ module defines the following exceptions:

876

907

877

908

`.. exception:: NetmaskValueError(ValueError)

878

909

879

Any value error related to the netmask.

910

Any value error related to the net mask.