815 lines
28 KiB
ReStructuredText
815 lines
28 KiB
ReStructuredText
:mod:`ipaddress` --- IPv4/IPv6 manipulation library
|
|
===================================================
|
|
|
|
.. module:: ipaddress
|
|
:synopsis: IPv4/IPv6 manipulation library.
|
|
.. moduleauthor:: Peter Moody
|
|
|
|
**Source code:** :source:`Lib/ipaddress.py`
|
|
|
|
--------------
|
|
|
|
:mod:`ipaddress` provides the capabilities to create, manipulate and
|
|
operate on IPv4 and IPv6 addresses and networks.
|
|
|
|
The functions and classes in this module make it straightforward to handle
|
|
various tasks related to IP addresses, including checking whether or not two
|
|
hosts are on the same subnet, iterating over all hosts in a particular
|
|
subnet, checking whether or not a string represents a valid IP address or
|
|
network definition, and so on.
|
|
|
|
This is the full module API reference—for an overview and introduction, see
|
|
:ref:`ipaddress-howto`.
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
|
|
Convenience factory functions
|
|
-----------------------------
|
|
|
|
The :mod:`ipaddress` module provides factory functions to conveniently create
|
|
IP addresses, networks and interfaces:
|
|
|
|
.. function:: ip_address(address)
|
|
|
|
Return an :class:`IPv4Address` or :class:`IPv6Address` object depending on
|
|
the IP address passed as argument. Either IPv4 or IPv6 addresses may be
|
|
supplied; integers less than 2**32 will be considered to be IPv4 by default.
|
|
A :exc:`ValueError` is raised if *address* does not represent a valid IPv4
|
|
or IPv6 address.
|
|
|
|
.. testsetup::
|
|
>>> import ipaddress
|
|
>>> from ipaddress import (ip_network, IPv4Address, IPv4Interface,
|
|
... IPv4Network)
|
|
|
|
::
|
|
|
|
>>> ipaddress.ip_address('192.168.0.1')
|
|
IPv4Address('192.168.0.1')
|
|
>>> ipaddress.ip_address('2001:db8::')
|
|
IPv6Address('2001:db8::')
|
|
|
|
|
|
.. function:: ip_network(address, strict=True)
|
|
|
|
Return an :class:`IPv4Network` or :class:`IPv6Network` object depending on
|
|
the IP address passed as argument. *address* is a string or integer
|
|
representing the IP network. Either IPv4 or IPv6 networks may be supplied;
|
|
integers less than 2**32 will be considered to be IPv4 by default. *strict*
|
|
is passed to :class:`IPv4Network` or :class:`IPv6Network` constructor. A
|
|
:exc:`ValueError` is raised if *address* does not represent a valid IPv4 or
|
|
IPv6 address, or if the network has host bits set.
|
|
|
|
>>> ipaddress.ip_network('192.168.0.0/28')
|
|
IPv4Network('192.168.0.0/28')
|
|
|
|
|
|
.. function:: ip_interface(address)
|
|
|
|
Return an :class:`IPv4Interface` or :class:`IPv6Interface` object depending
|
|
on the IP address passed as argument. *address* is a string or integer
|
|
representing the IP address. Either IPv4 or IPv6 addresses may be supplied;
|
|
integers less than 2**32 will be considered to be IPv4 by default. A
|
|
:exc:`ValueError` is raised if *address* does not represent a valid IPv4 or
|
|
IPv6 address.
|
|
|
|
One downside of these convenience functions is that the need to handle both
|
|
IPv4 and IPv6 formats means that error messages provide minimal
|
|
information on the precise error, as the functions don't know whether the
|
|
IPv4 or IPv6 format was intended. More detailed error reporting can be
|
|
obtained by calling the appropriate version specific class constructors
|
|
directly.
|
|
|
|
|
|
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
|
|
also implemented by :class:`IPv4Address` objects, in order to make it easier to
|
|
write code that handles both IP versions correctly.
|
|
|
|
.. class:: IPv4Address(address)
|
|
|
|
Construct an IPv4 address. An :exc:`AddressValueError` is raised if
|
|
*address* is not a valid IPv4 address.
|
|
|
|
The following constitutes a valid IPv4 address:
|
|
|
|
1. A string in decimal-dot notation, consisting of four decimal integers in
|
|
the inclusive range 0-255, separated by dots (e.g. ``192.168.0.1``). Each
|
|
integer represents an octet (byte) in the address. Leading zeroes are
|
|
tolerated only for values less than 8 (as there is no ambiguity
|
|
between the decimal and octal interpretations of such strings).
|
|
2. An integer that fits into 32 bits.
|
|
3. An integer packed into a :class:`bytes` object of length 4 (most
|
|
significant octet first).
|
|
|
|
>>> ipaddress.IPv4Address('192.168.0.1')
|
|
IPv4Address('192.168.0.1')
|
|
>>> ipaddress.IPv4Address(3232235521)
|
|
IPv4Address('192.168.0.1')
|
|
>>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01')
|
|
IPv4Address('192.168.0.1')
|
|
|
|
.. attribute:: version
|
|
|
|
The appropriate version number: ``4`` for IPv4, ``6`` for IPv6.
|
|
|
|
.. attribute:: max_prefixlen
|
|
|
|
The total number of bits in the address representation for this
|
|
version: ``32`` for IPv4, ``128`` for IPv6.
|
|
|
|
The prefix defines the number of leading bits in an address that
|
|
are compared to determine whether or not an address is part of a
|
|
network.
|
|
|
|
.. attribute:: compressed
|
|
.. attribute:: exploded
|
|
|
|
The string representation in dotted decimal notation. Leading zeroes
|
|
are never included in the representation.
|
|
|
|
As IPv4 does not define a shorthand notation for addresses with octets
|
|
set to zero, these two attributes are always the same as ``str(addr)``
|
|
for IPv4 addresses. Exposing these attributes makes it easier to
|
|
write display code that can handle both IPv4 and IPv6 addresses.
|
|
|
|
.. attribute:: packed
|
|
|
|
The binary representation of this address - a :class:`bytes` object of
|
|
the appropriate length (most significant octet first). This is 4 bytes
|
|
for IPv4 and 16 bytes for IPv6.
|
|
|
|
.. attribute:: is_multicast
|
|
|
|
``True`` if the address is reserved for multicast use. See
|
|
:RFC:`3171` (for IPv4) or :RFC:`2373` (for IPv6).
|
|
|
|
.. attribute:: is_private
|
|
|
|
``True`` if the address is allocated for private networks. See
|
|
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
|
|
(for IPv6).
|
|
|
|
.. attribute:: is_global
|
|
|
|
``True`` if the address is allocated for public networks. See
|
|
iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
|
|
(for IPv6).
|
|
|
|
.. versionadded:: 3.4
|
|
|
|
.. attribute:: is_unspecified
|
|
|
|
``True`` if the address is unspecified. See :RFC:`5735` (for IPv4)
|
|
or :RFC:`2373` (for IPv6).
|
|
|
|
.. attribute:: is_reserved
|
|
|
|
``True`` if the address is otherwise IETF reserved.
|
|
|
|
.. attribute:: is_loopback
|
|
|
|
``True`` if this is a loopback address. See :RFC:`3330` (for IPv4)
|
|
or :RFC:`2373` (for IPv6).
|
|
|
|
.. attribute:: is_link_local
|
|
|
|
``True`` if the address is reserved for link-local usage. See
|
|
:RFC:`3927`.
|
|
|
|
.. _iana-ipv4-special-registry: http://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
|
|
.. _iana-ipv6-special-registry: http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
|
|
|
|
|
|
.. class:: IPv6Address(address)
|
|
|
|
Construct an IPv6 address. An :exc:`AddressValueError` is raised if
|
|
*address* is not a valid IPv6 address.
|
|
|
|
The following constitutes a valid IPv6 address:
|
|
|
|
1. A string consisting of eight groups of four hexadecimal digits, each
|
|
group representing 16 bits. The groups are separated by colons.
|
|
This describes an *exploded* (longhand) notation. The string can
|
|
also be *compressed* (shorthand notation) by various means. See
|
|
:RFC:`4291` for details. For example,
|
|
``"0000:0000:0000:0000:0000:0abc:0007:0def"`` can be compressed to
|
|
``"::abc:7:def"``.
|
|
2. An integer that fits into 128 bits.
|
|
3. An integer packed into a :class:`bytes` object of length 16, big-endian.
|
|
|
|
>>> ipaddress.IPv6Address('2001:db8::1000')
|
|
IPv6Address('2001:db8::1000')
|
|
|
|
.. attribute:: compressed
|
|
|
|
The short form of the address representation, with leading zeroes in
|
|
groups omitted and the longest sequence of groups consisting entirely of
|
|
zeroes collapsed to a single empty group.
|
|
|
|
This is also the value returned by ``str(addr)`` for IPv6 addresses.
|
|
|
|
.. attribute:: exploded
|
|
|
|
The long form of the address representation, with all leading zeroes and
|
|
groups consisting entirely of zeroes included.
|
|
|
|
|
|
For the following attributes, see the corresponding documention of the
|
|
:class:`IPv4Address` class:
|
|
|
|
.. attribute:: packed
|
|
.. attribute:: version
|
|
.. attribute:: max_prefixlen
|
|
.. attribute:: is_multicast
|
|
.. attribute:: is_private
|
|
.. attribute:: is_global
|
|
.. attribute:: is_unspecified
|
|
.. attribute:: is_reserved
|
|
.. attribute:: is_loopback
|
|
.. attribute:: is_link_local
|
|
|
|
.. versionadded:: 3.4
|
|
is_global
|
|
|
|
.. attribute:: is_site_local
|
|
|
|
``True`` if the address is reserved for site-local usage. Note that
|
|
the site-local address space has been deprecated by :RFC:`3879`. Use
|
|
:attr:`~IPv4Address.is_private` to test if this address is in the
|
|
space of unique local addresses as defined by :RFC:`4193`.
|
|
|
|
.. attribute:: ipv4_mapped
|
|
|
|
For addresses that appear to be IPv4 mapped addresses (starting with
|
|
``::FFFF/96``), this property will report the embedded IPv4 address.
|
|
For any other address, this property will be ``None``.
|
|
|
|
.. attribute:: sixtofour
|
|
|
|
For addresses that appear to be 6to4 addresses (starting with
|
|
``2002::/16``) as defined by :RFC:`3056`, this property will report
|
|
the embedded IPv4 address. For any other address, this property will
|
|
be ``None``.
|
|
|
|
.. attribute:: teredo
|
|
|
|
For addresses that appear to be Teredo addresses (starting with
|
|
``2001::/32``) as defined by :RFC:`4380`, this property will report
|
|
the embedded ``(server, client)`` IP address pair. For any other
|
|
address, this property will be ``None``.
|
|
|
|
|
|
Conversion to Strings and Integers
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
To interoperate with networking interfaces such as the socket module,
|
|
addresses must be converted to strings or integers. This is handled using
|
|
the :func:`str` and :func:`int` builtin functions::
|
|
|
|
>>> str(ipaddress.IPv4Address('192.168.0.1'))
|
|
'192.168.0.1'
|
|
>>> int(ipaddress.IPv4Address('192.168.0.1'))
|
|
3232235521
|
|
>>> str(ipaddress.IPv6Address('::1'))
|
|
'::1'
|
|
>>> int(ipaddress.IPv6Address('::1'))
|
|
1
|
|
|
|
|
|
Operators
|
|
^^^^^^^^^
|
|
|
|
Address objects support some operators. Unless stated otherwise, operators can
|
|
only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
|
|
IPv6).
|
|
|
|
|
|
Comparison operators
|
|
""""""""""""""""""""
|
|
|
|
Address objects can be compared with the usual set of comparison operators. Some
|
|
examples::
|
|
|
|
>>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1')
|
|
True
|
|
>>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1')
|
|
False
|
|
>>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1')
|
|
True
|
|
|
|
|
|
Arithmetic operators
|
|
""""""""""""""""""""
|
|
|
|
Integers can be added to or subtracted from address objects. Some examples::
|
|
|
|
>>> IPv4Address('127.0.0.2') + 3
|
|
IPv4Address('127.0.0.5')
|
|
>>> IPv4Address('127.0.0.2') - 3
|
|
IPv4Address('126.255.255.255')
|
|
>>> IPv4Address('255.255.255.255') + 1
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
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*
|
|
``/<nbits>`` 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 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
|
|
to determine the appropriate network address.
|
|
|
|
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
|
|
:class:`IPv4Address`
|
|
|
|
.. 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
|
|
for both the network address and the broadcast address
|
|
|
|
.. attribute:: network_address
|
|
|
|
The network address for the network. The network address and the
|
|
prefix length together uniquely define a network.
|
|
|
|
.. attribute:: broadcast_address
|
|
|
|
The broadcast address for the network. Packets sent to the broadcast
|
|
address should be received by every host on the network.
|
|
|
|
.. attribute:: hostmask
|
|
|
|
The host mask, as a string.
|
|
|
|
.. attribute:: with_prefixlen
|
|
.. attribute:: compressed
|
|
.. attribute:: exploded
|
|
|
|
A string representation of the network, with the mask in prefix
|
|
notation.
|
|
|
|
``with_prefixlen`` and ``compressed`` are always the same as
|
|
``str(network)``.
|
|
``exploded`` uses the exploded form the network address.
|
|
|
|
.. 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 network prefix, in bits.
|
|
|
|
.. method:: hosts()
|
|
|
|
Returns 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.
|
|
|
|
>>> list(ip_network('192.0.2.0/29').hosts()) #doctest: +NORMALIZE_WHITESPACE
|
|
[IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'),
|
|
IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'),
|
|
IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')]
|
|
|
|
.. method:: overlaps(other)
|
|
|
|
``True`` if this network is partly or wholly contained in *other* or
|
|
*other* is wholly contained in this network.
|
|
|
|
.. method:: address_exclude(network)
|
|
|
|
Computes the network definitions resulting from removing the given
|
|
*network* from this one. Returns an iterator of network objects.
|
|
Raises :exc:`ValueError` if *network* is not completely contained in
|
|
this network.
|
|
|
|
>>> n1 = ip_network('192.0.2.0/28')
|
|
>>> n2 = ip_network('192.0.2.1/32')
|
|
>>> list(n1.address_exclude(n2)) #doctest: +NORMALIZE_WHITESPACE
|
|
[IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'),
|
|
IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')]
|
|
|
|
.. 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.
|
|
|
|
>>> list(ip_network('192.0.2.0/24').subnets())
|
|
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]
|
|
>>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2)) #doctest: +NORMALIZE_WHITESPACE
|
|
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
|
|
IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
|
|
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26)) #doctest: +NORMALIZE_WHITESPACE
|
|
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
|
|
IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
|
|
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23))
|
|
Traceback (most recent call last):
|
|
File "<stdin>", line 1, in <module>
|
|
raise ValueError('new prefix must be longer')
|
|
ValueError: new prefix must be longer
|
|
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25))
|
|
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]
|
|
|
|
.. 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.
|
|
|
|
>>> ip_network('192.0.2.0/24').supernet()
|
|
IPv4Network('192.0.2.0/23')
|
|
>>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2)
|
|
IPv4Network('192.0.0.0/22')
|
|
>>> ip_network('192.0.2.0/24').supernet(new_prefix=20)
|
|
IPv4Network('192.0.0.0/20')
|
|
|
|
.. 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``.
|
|
|
|
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32'))
|
|
-1
|
|
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32'))
|
|
1
|
|
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32'))
|
|
0
|
|
|
|
|
|
.. class:: IPv6Network(address, strict=True)
|
|
|
|
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 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 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, big-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
|
|
to determine the appropriate network address.
|
|
|
|
.. 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:: hostmask
|
|
.. 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)
|
|
|
|
Refer to the corresponding attribute documentation in
|
|
:class:`IPv4Network`
|
|
|
|
.. attribute:: is_site_local
|
|
|
|
These attribute is true for the network as a whole if it is true
|
|
for both the network address and the broadcast address
|
|
|
|
|
|
Operators
|
|
^^^^^^^^^
|
|
|
|
Network objects support some operators. Unless stated otherwise, operators can
|
|
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
|
|
"""""""""
|
|
|
|
Network objects can be iterated to list all the addresses belonging to the
|
|
network. For iteration, *all* hosts are returned, including unusable hosts
|
|
(for usable hosts, use the :meth:`~IPv4Network.hosts` method). An
|
|
example::
|
|
|
|
>>> for addr in IPv4Network('192.0.2.0/28'):
|
|
... addr
|
|
...
|
|
IPv4Address('192.0.2.0')
|
|
IPv4Address('192.0.2.1')
|
|
IPv4Address('192.0.2.2')
|
|
IPv4Address('192.0.2.3')
|
|
IPv4Address('192.0.2.4')
|
|
IPv4Address('192.0.2.5')
|
|
IPv4Address('192.0.2.6')
|
|
IPv4Address('192.0.2.7')
|
|
IPv4Address('192.0.2.8')
|
|
IPv4Address('192.0.2.9')
|
|
IPv4Address('192.0.2.10')
|
|
IPv4Address('192.0.2.11')
|
|
IPv4Address('192.0.2.12')
|
|
IPv4Address('192.0.2.13')
|
|
IPv4Address('192.0.2.14')
|
|
IPv4Address('192.0.2.15')
|
|
|
|
|
|
Networks as containers of addresses
|
|
"""""""""""""""""""""""""""""""""""
|
|
|
|
Network objects can act as containers of addresses. Some examples::
|
|
|
|
>>> IPv4Network('192.0.2.0/28')[0]
|
|
IPv4Address('192.0.2.0')
|
|
>>> IPv4Network('192.0.2.0/28')[15]
|
|
IPv4Address('192.0.2.15')
|
|
>>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28')
|
|
True
|
|
>>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28')
|
|
False
|
|
|
|
|
|
Interface objects
|
|
-----------------
|
|
|
|
.. class:: IPv4Interface(address)
|
|
|
|
Construct an IPv4 interface. The meaning of *address* is as in the
|
|
constructor of :class:`IPv4Network`, except that arbitrary host addresses
|
|
are always accepted.
|
|
|
|
:class:`IPv4Interface` is a subclass of :class:`IPv4Address`, so it inherits
|
|
all the attributes from that class. In addition, the following attributes
|
|
are available:
|
|
|
|
.. attribute:: ip
|
|
|
|
The address (:class:`IPv4Address`) without network information.
|
|
|
|
>>> interface = IPv4Interface('192.0.2.5/24')
|
|
>>> interface.ip
|
|
IPv4Address('192.0.2.5')
|
|
|
|
.. attribute:: network
|
|
|
|
The network (:class:`IPv4Network`) this interface belongs to.
|
|
|
|
>>> interface = IPv4Interface('192.0.2.5/24')
|
|
>>> interface.network
|
|
IPv4Network('192.0.2.0/24')
|
|
|
|
.. attribute:: with_prefixlen
|
|
|
|
A string representation of the interface with the mask in prefix notation.
|
|
|
|
>>> interface = IPv4Interface('192.0.2.5/24')
|
|
>>> interface.with_prefixlen
|
|
'192.0.2.5/24'
|
|
|
|
.. attribute:: with_netmask
|
|
|
|
A string representation of the interface with the network as a net mask.
|
|
|
|
>>> interface = IPv4Interface('192.0.2.5/24')
|
|
>>> interface.with_netmask
|
|
'192.0.2.5/255.255.255.0'
|
|
|
|
.. attribute:: with_hostmask
|
|
|
|
A string representation of the interface with the network as a host mask.
|
|
|
|
>>> interface = IPv4Interface('192.0.2.5/24')
|
|
>>> interface.with_hostmask
|
|
'192.0.2.5/0.0.0.255'
|
|
|
|
|
|
.. class:: IPv6Interface(address)
|
|
|
|
Construct an IPv6 interface. The meaning of *address* is as in the
|
|
constructor of :class:`IPv6Network`, except that arbitrary host addresses
|
|
are always accepted.
|
|
|
|
:class:`IPv6Interface` is a subclass of :class:`IPv6Address`, so it inherits
|
|
all the attributes from that class. In addition, the following attributes
|
|
are available:
|
|
|
|
.. attribute:: ip
|
|
.. attribute:: network
|
|
.. attribute:: with_prefixlen
|
|
.. attribute:: with_netmask
|
|
.. attribute:: with_hostmask
|
|
|
|
Refer to the corresponding attribute documentation in
|
|
:class:`IPv4Interface`.
|
|
|
|
|
|
Other Module Level Functions
|
|
----------------------------
|
|
|
|
The module also provides the following module level functions:
|
|
|
|
.. function:: v4_int_to_packed(address)
|
|
|
|
Represent an address as 4 packed bytes in network (big-endian) order.
|
|
*address* is an integer representation of an IPv4 IP address. A
|
|
:exc:`ValueError` is raised if the integer is negative or too large to be an
|
|
IPv4 IP address.
|
|
|
|
>>> ipaddress.ip_address(3221225985)
|
|
IPv4Address('192.0.2.1')
|
|
>>> ipaddress.v4_int_to_packed(3221225985)
|
|
b'\xc0\x00\x02\x01'
|
|
|
|
|
|
.. function:: v6_int_to_packed(address)
|
|
|
|
Represent an address as 16 packed bytes in network (big-endian) order.
|
|
*address* is an integer representation of an IPv6 IP address. A
|
|
:exc:`ValueError` is raised if the integer is negative or too large to be an
|
|
IPv6 IP address.
|
|
|
|
|
|
.. function:: summarize_address_range(first, last)
|
|
|
|
Return an iterator of the summarized network range given the first and last
|
|
IP addresses. *first* is the first :class:`IPv4Address` or
|
|
:class:`IPv6Address` in the range and *last* is the last :class:`IPv4Address`
|
|
or :class:`IPv6Address` in the range. A :exc:`TypeError` is raised if
|
|
*first* or *last* are not IP addresses or are not of the same version. A
|
|
:exc:`ValueError` is raised if *last* is not greater than *first* or if
|
|
*first* address version is not 4 or 6.
|
|
|
|
>>> [ipaddr for ipaddr in ipaddress.summarize_address_range(
|
|
... ipaddress.IPv4Address('192.0.2.0'),
|
|
... ipaddress.IPv4Address('192.0.2.130'))]
|
|
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')]
|
|
|
|
|
|
.. function:: collapse_addresses(addresses)
|
|
|
|
Return an iterator of the collapsed :class:`IPv4Network` or
|
|
:class:`IPv6Network` objects. *addresses* is an iterator of
|
|
:class:`IPv4Network` or :class:`IPv6Network` objects. A :exc:`TypeError` is
|
|
raised if *addresses* contains mixed version objects.
|
|
|
|
>>> [ipaddr for ipaddr in
|
|
... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'),
|
|
... ipaddress.IPv4Network('192.0.2.128/25')])]
|
|
[IPv4Network('192.0.2.0/24')]
|
|
|
|
|
|
.. function:: get_mixed_type_key(obj)
|
|
|
|
Return a key suitable for sorting between networks and addresses. Address
|
|
and Network objects are not sortable by default; they're fundamentally
|
|
different, so the expression::
|
|
|
|
IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')
|
|
|
|
doesn't make sense. There are some times however, where you may wish to
|
|
have :mod:`ipaddress` sort these anyway. If you need to do this, you can use
|
|
this function as the ``key`` argument to :func:`sorted()`.
|
|
|
|
*obj* is either a network or address object.
|
|
|
|
|
|
Custom Exceptions
|
|
-----------------
|
|
|
|
To support more specific error reporting from class constructors, the
|
|
module defines the following exceptions:
|
|
|
|
.. exception:: AddressValueError(ValueError)
|
|
|
|
Any value error related to the address.
|
|
|
|
|
|
.. exception:: NetmaskValueError(ValueError)
|
|
|
|
Any value error related to the netmask.
|