cpython: cf8d42596a44 (original) (raw)

--- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -196,10 +196,6 @@ write code that handles both IP versions >>> ipaddress.IPv6Address('2001:db8::1000') IPv6Address('2001:db8::1000')

All the attributes implemented by :class:IPv4Address are supported. In
addition, the following attributs are implemented only by
:class:IPv6Address. - .. attribute:: compressed The short form of the address representation, with leading zeroes in @@ -372,119 +368,149 @@ so to avoid duplication they are only do then :exc:ValueError is raised. Otherwise, the host bits are masked out to determine the appropriate network address.
This class implements all the attributes of :class:IPv4Address, and also
the following attributes and methods. Unless stated otherwise, all methods
accepting other network / address objects will raise :exc:TypeError if
the argument's IP version is incompatible to self:

Unless stated otherwise, all network methods accepting other network/address
objects will raise :exc:TypeError if the argument's IP version is
incompatible to self +
.. attribute:: version
.. attribute:: max_prefixlen +

 Refer to the corresponding attribute documentation in[](#l1.29)

```
 :class:`IPv4Address`[](#l1.30)
```

.. attribute:: is_multicast
.. attribute:: is_private
.. attribute:: is_unspecified
.. attribute:: is_reserved
.. attribute:: is_loopback
.. attribute:: is_link_local +

 These attributes are true for the network as a whole if they are true[](#l1.39)

 true for both the network address and the broadcast address[](#l1.40)

.. attribute:: network_address +

 The broadcast address for the network.[](#l1.44)

.. attribute:: broadcast_address

The broadcast address for the network.

 The broadcast address for the network.[](#l1.49)

.. attribute:: host mask

The host mask, as a string.

```
 The host mask, as a string.[](#l1.54)
```

.. attribute:: with_prefixlen

.. attribute:: compressed
.. attribute:: exploded

A string representation of the network, with the mask in prefix notation.

 A string representation of the network, with the mask in prefix[](#l1.61)

```
 notation.[](#l1.62)
```

 ``with_prefixlen`` and ``compressed`` are always the same as[](#l1.64)

```
 ``str(network)``.[](#l1.65)
```

 ``exploded`` uses the exploded form the network address.[](#l1.66)

.. attribute:: with_netmask

A string representation of the network, with the mask in net mask notation.

 A string representation of the network, with the mask in net mask[](#l1.71)

```
 notation.[](#l1.72)
```

.. attribute:: with_hostmask

A string representation of the network, with the mask in host mask notation.

 A string representation of the network, with the mask in host mask[](#l1.77)

```
 notation.[](#l1.78)
```

.. attribute:: num_addresses

The total number of addresses in the network.

 The total number of addresses in the network.[](#l1.83)

.. attribute:: prefixlen

Length of the prefix, in bits.

 Length of the network prefix, in bits.[](#l1.88)

.. method:: hosts()

Generates an iterator over the usable hosts in the network. The usable hosts
are all the IP addresses that belong to the network, except the network
address itself and the network broadcast address.

 Returns an iterator over the usable hosts in the network.  The usable[](#l1.95)

 hosts are all the IP addresses that belong to the network, except the[](#l1.96)

 network address itself and the network broadcast address.[](#l1.97)

 >>> list(ip_network('192.0.2.0/29').hosts())[](#l1.99)

 [IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'),[](#l1.100)

  IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'),[](#l1.101)

  IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')][](#l1.102)

    >>> list(ip_network('192.0.2.0/29').hosts())[](#l1.103)

    [IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'),[](#l1.104)

     IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'),[](#l1.105)

     IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')][](#l1.106)

.. method:: overlaps(other)

True if this network is partly contained in other.

 ``True`` if this network is partly or wholly contained in *other* or[](#l1.111)

 or *other* is wholly contained in this network.[](#l1.112)

.. method:: address_exclude(network)

Computes the network defintions resulting from removing the given network
from this one. Returns a generator. Raises :exc:ValueError if network
is not completely contained in this network.

 Computes the network definitions resulting from removing the given[](#l1.119)

 *network* from this one.  Returns an iterator of network objects.[](#l1.120)

 Raises :exc:`ValueError` if *network* is not completely contained in[](#l1.121)

```
 this network.[](#l1.122)
```

 >>> n1 = ip_network('192.0.2.0/28')[](#l1.124)

 >>> n2 = ip_network('192.0.2.1/32')[](#l1.125)

 >>> list(n1.address_exclude(n2))[](#l1.126)

 [IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'),[](#l1.127)

  IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')][](#l1.128)

    >>> n1 = ip_network('192.0.2.0/28')[](#l1.129)

    >>> n2 = ip_network('192.0.2.1/32')[](#l1.130)

    >>> list(n1.address_exclude(n2))[](#l1.131)

    [IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'),[](#l1.132)

     IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')][](#l1.133)

.. method:: subnets(prefixlen_diff=1, new_prefix=None)

The subnets that join to make the current network definition, depending on
the argument values. prefixlen_diff is the amount our prefix length
should be increased by. new_prefix is the desired new prefix of the
subnets; it must be larger than our prefix. One and only one of
prefixlen_diff and new_prefix must be set. Returns an iterator of
network objects.

 The subnets that join to make the current network definition, depending[](#l1.143)

 on the argument values.  *prefixlen_diff* is the amount our prefix[](#l1.144)

 length should be increased by.  *new_prefix* is the desired new[](#l1.145)

 prefix of the subnets; it must be larger than our prefix.  One and[](#l1.146)

 only one of *prefixlen_diff* and *new_prefix* must be set.  Returns an[](#l1.147)

 iterator of network objects.[](#l1.148)

 >>> list(ip_network('192.0.2.0/24').subnets())[](#l1.150)

 [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')][](#l1.151)

 >>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2))[](#l1.152)

 [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),[](#l1.153)

  IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')][](#l1.154)

 >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26))[](#l1.155)

 [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),[](#l1.156)

  IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')][](#l1.157)

 >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23))[](#l1.158)

 Traceback (most recent call last):[](#l1.159)

   File "<stdin>", line 1, in <module>[](#l1.160)

     raise ValueError('new prefix must be longer')[](#l1.161)

 ValueError: new prefix must be longer[](#l1.162)

 >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25))[](#l1.163)

 [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')][](#l1.164)

```
 >>>[](#l1.165)
```

    >>> list(ip_network('192.0.2.0/24').subnets())[](#l1.166)

    [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')][](#l1.167)

    >>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2))[](#l1.168)

    [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),[](#l1.169)

     IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')][](#l1.170)

    >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26))[](#l1.171)

    [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),[](#l1.172)

     IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')][](#l1.173)

    >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23))[](#l1.174)

    Traceback (most recent call last):[](#l1.175)

      File "<stdin>", line 1, in <module>[](#l1.176)

        raise ValueError('new prefix must be longer')[](#l1.177)

    ValueError: new prefix must be longer[](#l1.178)

    >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25))[](#l1.179)

    [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')][](#l1.180)

.. method:: supernet(prefixlen_diff=1, new_prefix=None)

The supernet containing this network definition, depending on the argument
values. prefixlen_diff is the amount our prefix length should be
decreased by. new_prefix is the desired new prefix of the supernet; it
must be smaller than our prefix. One and only one of prefixlen_diff and
new_prefix must be set. Returns a single network object.

 The supernet containing this network definition, depending on the[](#l1.189)

 argument values.  *prefixlen_diff* is the amount our prefix length[](#l1.190)

 should be decreased by.  *new_prefix* is the desired new prefix of[](#l1.191)

 the supernet; it must be smaller than our prefix.  One and only one[](#l1.192)

 of *prefixlen_diff* and *new_prefix* must be set.  Returns a single[](#l1.193)

```
 network object.[](#l1.194)
```

 >>> ip_network('192.0.2.0/24').supernet()[](#l1.196)

```
 IPv4Network('192.0.2.0/23')[](#l1.197)
```

 >>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2)[](#l1.198)

```
 IPv4Network('192.0.0.0/22')[](#l1.199)
```

 >>> ip_network('192.0.2.0/24').supernet(new_prefix=20)[](#l1.200)

```
 IPv4Network('192.0.0.0/20')[](#l1.201)
```

    >>> ip_network('192.0.2.0/24').supernet()[](#l1.202)

    IPv4Network('192.0.2.0/23')[](#l1.203)

    >>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2)[](#l1.204)

    IPv4Network('192.0.0.0/22')[](#l1.205)

    >>> ip_network('192.0.2.0/24').supernet(new_prefix=20)[](#l1.206)

    IPv4Network('192.0.0.0/20')[](#l1.207)

.. method:: compare_networks(other)

Compare this network to other. In this comparison only the network
addresses are considered; host bits aren't. Returns either -1, 0
or 1.

 Compare this network to *other*.  In this comparison only the network[](#l1.214)

 addresses are considered; host bits aren't.  Returns either ``-1``,[](#l1.215)

```
 ``0`` or ``1``.[](#l1.216)
```

 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32'))[](#l1.218)

```
 -1[](#l1.219)
```

 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32'))[](#l1.220)

```
 1[](#l1.221)
```

 >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32'))[](#l1.222)

```
 0[](#l1.223)
```

    >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32'))[](#l1.224)

```
    -1[](#l1.225)
```

    >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32'))[](#l1.226)

```
    1[](#l1.227)
```

    >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32'))[](#l1.228)

```
    0[](#l1.229)
```

.. class:: IPv6Network(address, strict=True) @@ -492,7 +518,7 @@ so to avoid duplication they are only do Construct an IPv6 network definition. address can be one of the following: 1. A string consisting of an IP address and an optional mask, separated by

 a slash (``/``).  The IP addrses is the network address, and the mask[](#l1.237)

 a slash (``/``).  The IP address is the network address, and the mask[](#l1.238)
 can be either a single number, which means it's a *prefix*, or a string[](#l1.239)
 representation of an IPv6 address.  If it's the latter, the mask is[](#l1.240)
 interpreted as a *net mask*.  If no mask is provided, it's considered to[](#l1.241)

@@ -516,10 +542,38 @@ so to avoid duplication they are only do then :exc:ValueError is raised. Otherwise, the host bits are masked out to determine the appropriate network address.

.. describe:: Attributes and methods

.. attribute:: version
.. attribute:: max_prefixlen
.. attribute:: is_multicast
.. attribute:: is_private
.. attribute:: is_unspecified
.. attribute:: is_reserved
.. attribute:: is_loopback
.. attribute:: is_link_local
.. attribute:: network_address
.. attribute:: broadcast_address
.. attribute:: host mask
.. attribute:: with_prefixlen
.. attribute:: compressed
.. attribute:: exploded
.. attribute:: with_netmask
.. attribute:: with_hostmask
.. attribute:: num_addresses
.. attribute:: prefixlen
.. method:: hosts()
.. method:: overlaps(other)
.. method:: address_exclude(network)
.. method:: subnets(prefixlen_diff=1, new_prefix=None)
.. method:: supernet(prefixlen_diff=1, new_prefix=None)
.. method:: compare_networks(other)

All attributes and methods implemented by :class:IPv4Network and by
:class:IPv6Address are also implemented by :class:IPv6Network.

 Refer to the corresponding attribute documentation in[](#l1.274)

```
 :class:`IPv4Network`[](#l1.275)
```

.. attribute:: is_site_local +

 These attribute is true for the network as a whole if it is true[](#l1.279)

 true for both the network address and the broadcast address[](#l1.280)

Operators @@ -529,12 +583,14 @@ Network objects support some operators. only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with IPv6). + Logical operators """"""""""""""""" Network objects can be compared with the usual set of logical operators, similarly to address objects. + Iteration """"""""" @@ -563,6 +619,7 @@ example:: IPv4Address('192.0.2.14') IPv4Address('192.0.2.15') + Networks as containers of addresses """""""""""""""""""""""""""""""""""