diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -66,8 +66,11 @@ IPv6 address. +IP Addresses +------------ + Address objects ---------------- +^^^^^^^^^^^^^^^ The :class:`IPv4Address` and :class:`IPv6Address` objects share a lot of common attributes. Some attributes that are only meaningful for IPv6 addresses are @@ -165,8 +168,9 @@ >>> ipaddress.IPv6Address('2001:db8::1000') IPv6Address('2001:db8::1000') - All the attributes exposed by :class:`IPv4Address` are supported. In - addition, the following attributs are exposed only by :class:`IPv6Address`. + All the attributes implemented by :class:`IPv4Address` are supported. In + addition, the following attributs are implemented only by + :class:`IPv6Address`. .. attribute:: is_site_local @@ -227,45 +231,135 @@ ipaddress.AddressValueError: 4294967296 (>= 2**32) is not permitted as an IPv4 address +IP Network definitions +---------------------- + +The :class:`IPv4Network` and :class:`IPv6Network` objects provide a mechanism +for defining and inspecting IP network definitions. A network definition +consists of a *mask* and a *network address*, and as such defines a range of +IP addresses that equal the network address when masked (binary AND) with the +mask. For example, a network definition with the mask ``255.255.255.0`` and +the network address ``192.168.1.0`` consists of IP addresses in the inclusive +range ``192.168.1.0`` to ``192.168.1.255``. + + +Prefix, net mask and host mask +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are several equivalent ways to specify IP network masks. A *prefix* +``/`` is a notation that denotes how many high-order bits are set in +the network mask. A *net mask* is an IP address with some number of +high-order bits set. Thus the prefix ``/24`` is equivalent to the net mask +``255.255.255.0`` in IPv4, or ``ffff:ff00::`` in IPv6. In addition, a +*host mask* is the logical inverse of a *net mask*, and is sometimes used +(for example in Cisco access control lists) to denote a network mask. The +host mask equivalent to ``/24`` in IPv4 is ``0.0.0.255``. + + Network objects ---------------- +^^^^^^^^^^^^^^^ + +All attributes implemented by address objects are implemented by network +objects as well. In addition, network objects implement additional attributes. +All of these are common between :class:`IPv4Network` and :class:`IPv6Network`, +so to avoid duplication they are only documented for :class:`IPv4Network`. .. class:: IPv4Network(address, strict=True) - Construct an IPv4 network. *address* is a string or integer representing the - IP address (and optionally the network). An :exc:`AddressValueError` is - raised if *address* is not a valid IPv4 address. A :exc:`NetmaskValueError` - is raised if the netmask is not valid for an IPv4 address. + Construct an IPv4 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 address is the network address, and the mask + can be either a single number, which means it's a *prefix*, or a string + representation of an IPv4 address. If it's the latter, the mask is + interpreted as a *net mask* if it starts with a non-zero field, or as + a *host mask* if it starts with a zero field. If no mask is provided, + it's considered to be ``/32``. + + For example, the following *address* specifications are equivalent: + ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and + ``192.168.1.0/0.0.0.255``. + + 2. An integer that fits into 32 bits. This is equivalent to a + single-address network, with the network address being *address* and + the mask being ``/32``. + + 3. An integer packed into a :class:`bytes` object of length 4, big-endian. + The interpretation is similar to an integer *address*. + + An :exc:`AddressValueError` is raised if *address* is not a valid IPv4 + address. A :exc:`NetmaskValueError` is raised if the mask is not valid for + an IPv4 address. If *strict* is ``True`` and host bits are set in the supplied address, - then :exc:`ValueError` is raised. Otherwise, the host bits are masked out + then :exc:`ValueError` is raised. Otherwise, the host bits are masked out to determine the appropriate network address. - >>> ipaddress.IPv4Network('192.0.2.0/27') - IPv4Network('192.0.2.0/27') - >>> ipaddress.IPv4Network('192.0.2.0/27').netmask - IPv4Address('255.255.255.224') - >>> ipaddress.IPv4Network('192.0.2.5/27', strict=False) - IPv4Network('192.0.2.0/27') + This class implements all the attributes of :class:`IPv4Address`, and also + the following attributes: + + .. attribute:: broadcast_address + + The broadcast address for the network. + + .. attribute:: host mask + + The host mask, as a string. + + .. attribute:: with_prefixlen + + A string representation of the network, with the mask in prefix notation. + + .. attribute:: with_netmask + + A string representation of the network, with the mask in net mask notation. + + .. attribute:: with_hostmask + + A string representation of the network, with the mask in host mask notation. + + .. attribute:: num_addresses + + The total number of addresses in the network. + + .. attribute:: prefixlen + + Length of the prefix, in bits. .. class:: IPv6Network(address, strict=True) - Construct an IPv6 network. *address* is a string or integer representing the - IP address (and optionally the network). An :exc:`AddressValueError` is - raised if *address* is not a valid IPv6 address. A :exc:`NetmaskValueError` - is raised if the netmask is not valid for an IPv6 address. + 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 + can be either a single number, which means it's a *prefix*, or a string + representation of an IPv6 address. If it's the latter, the mask is + interpreted as a *net mask*. If no mask is provided, it's considered to + be ``/128``. + + For example, the following *address* specifications are equivalent: + ``2001:db00::0/24`` and ``2001:db00::0/ffff:ff00::``. + + 2. An integer that fits into 128 bits. This is equivalent to a + single-address network, with the network address being *address* and + the mask being ``/128``. + + 3. An integer packed into a :class:`bytes` object of length 16, bit-endian. + The interpretation is similar to an integer *address*. + + An :exc:`AddressValueError` is raised if *address* is not a valid IPv6 + address. A :exc:`NetmaskValueError` is raised if the mask is not valid for + an IPv6 address. If *strict* is ``True`` and host bits are set in the supplied address, - then :exc:`ValueError` is raised. Otherwise, the host bits are masked out + then :exc:`ValueError` is raised. Otherwise, the host bits are masked out to determine the appropriate network address. - >>> ipaddress.IPv6Network('2001:db8::/96') - IPv6Network('2001:db8::/96') - >>> ipaddress.IPv6Network('2001:db8::/96').netmask - IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::') - >>> ipaddress.IPv6Network('2001:db8::1000/96', strict=False) - IPv6Network('2001:db8::/96') + .. describe:: Attributes and methods + + All attributes and methods implemented by :class:`IPv4Network` and by + :class:`IPv6Address` are also implemented by :class:`IPv6Network`. Interface objects