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

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

89

`` The :class:IPv4Address and :class:IPv6Address objects share a lot of common

90

`attributes. Some attributes that are only meaningful for IPv6 addresses are

91

`` also implemented by :class:IPv4Address objects, in order to make it easier to

92

write code that handles both IP versions correctly.

92

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

93

`` +

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

93

94

95

`.. class:: IPv4Address(address)

95

96

`@@ -366,6 +367,8 @@ All attributes implemented by address objects are implemented by network

366

367

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

367

368

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

368

369

`` so to avoid duplication they are only documented for :class:IPv4Network.

370

`` +

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

371

dictionaries.

369

372

370

373

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

371

374

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

375

378

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


`376`

`379`

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

`

`377`

`380`

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

`

``

`381`

`+

interpreted as a *net mask* if it starts with a non-zero field, or as a

`

``

`382`

`+

*host mask* if it starts with a zero field, with the single exception of

`

``

`383`

`+

an all-zero mask which is treated as a *net mask*. If no mask is provided,

`

`380`

`384`

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

381

385

382

386

` For example, the following address specifications are equivalent:

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

406

410

407

411

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

408

412

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

409


 incompatible to ``self``

413


 incompatible to ``self``.

410

414

411

415

` .. versionchanged:: 3.5

412

416

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

416

420

` .. attribute:: max_prefixlen

417

421

418

422

` Refer to the corresponding attribute documentation in

419

`` -

:class:IPv4Address

423

`` +

:class:IPv4Address.

420

424

421

425

` .. attribute:: is_multicast

422

426

` .. attribute:: is_private

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

426

430

` .. attribute:: is_link_local

427

431

428

432

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

429

for both the network address and the broadcast address

433

for both the network address and the broadcast address.

430

434

431

435

` .. attribute:: network_address

432

436

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

563

567

564

568

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

565

569

566

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

567


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

568

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

569


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

570

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

571


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

572

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

573


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

570

574

571

575

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

572

576

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


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

``

`623`

`627`

` .. method:: compare_networks(other)

`

`624`

`628`

``

`625`

`629`

` Refer to the corresponding attribute documentation in

`

`626`

``

`` -

:class:`IPv4Network`

``

``

`630`

`` +

:class:`IPv4Network`.

``

`627`

`631`

``

`628`

`632`

` .. attribute:: is_site_local

`

`629`

`633`

``

`630`

`634`

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

`

`631`

``

`-

for both the network address and the broadcast address

`

``

`635`

`+

for both the network address and the broadcast address.

`

`632`

`636`

``

`633`

`637`

``

`634`

`638`

`Operators

`

`@@ -642,8 +646,8 @@ IPv6).

`

`642`

`646`

`Logical operators

`

`643`

`647`

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

`

`644`

`648`

``

`645`

``

`-

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

`

`646`

``

`-

similarly to address objects.

`

``

`649`

`+

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

`

``

`650`

`+

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

`

`647`

`651`

``

`648`

`652`

``

`649`

`653`

`Iteration

`

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

`

`693`

`697`

`Interface objects

`

`694`

`698`

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

`

`695`

`699`

``

``

`700`

`` +

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

``

``

`701`

`+

dictionaries.

`

``

`702`

`+`

`696`

`703`

`.. class:: IPv4Interface(address)

`

`697`

`704`

``

`698`

`705`

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

`

`@@ -764,6 +771,30 @@ Interface objects

`

`764`

`771`

`` :class:`IPv4Interface`.

``

`765`

`772`

``

`766`

`773`

``

``

`774`

`+

Operators

`

``

`775`

`+

^^^^^^^^^

`

``

`776`

`+`

``

`777`

`+

Interface objects support some operators. Unless stated otherwise, operators

`

``

`778`

`+

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

`

``

`779`

`+

IPv6).

`

``

`780`

`+`

``

`781`

`+`

``

`782`

`+

Logical operators

`

``

`783`

`+

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

`

``

`784`

`+`

``

`785`

`+

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

`

``

`786`

`+`

``

`787`

``` +

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

788

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

789

equal to any address or network object.

790

+

791


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

792

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

793

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

794

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

795

IP addresses.

796

+

797

+

767

798

`Other Module Level Functions

768

799

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

769

800

`@@ -829,7 +860,7 @@ The module also provides the following module level functions:

829

860

830

861

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

831

862

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

832


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

863

`` +

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

833

864

834

865

` obj is either a network or address object.

835

866

`@@ -847,4 +878,4 @@ module defines the following exceptions:

847

878

848

879

`.. exception:: NetmaskValueError(ValueError)

849

880

850

Any value error related to the netmask.

881

Any value error related to the net mask.