252 lines
9.0 KiB
ReStructuredText
252 lines
9.0 KiB
ReStructuredText
:mod:`ipaddress` --- IPv4/IPv6 manipulation library
|
|
===================================================
|
|
|
|
.. module:: ipaddress
|
|
:synopsis: IPv4/IPv6 manipulation library.
|
|
.. moduleauthor:: Peter Moody
|
|
|
|
**Source code:** :source:`Lib/ipaddress.py`
|
|
|
|
--------------
|
|
|
|
The :mod:`ipaddress` module provides the capabilities to create, manipulate and
|
|
operate on IPv4 and IPv6 addresses and networks.
|
|
|
|
This is the full module API reference - for an overview and introduction,
|
|
see :ref:`ipaddress-howto`.
|
|
|
|
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, as well as checking whether or not a string represents a valid
|
|
IP address or network definition.
|
|
|
|
|
|
Defining IP Addresses and Interfaces
|
|
------------------------------------
|
|
|
|
The :mod:`ipaddress` module provides factory functions to define IP addresses
|
|
and networks:
|
|
|
|
.. function:: ip_address(address)
|
|
|
|
Return an :class:`IPv4Address` or :class:`IPv6Address` 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 the *address* passed is neither an IPv4 nor
|
|
IPv6 address.
|
|
|
|
>>> 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 the string passed isn't either an 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 the *address* passed isn't either an IPv4 or
|
|
IPv6 address.
|
|
|
|
|
|
Representing IP Addresses and Networks
|
|
--------------------------------------
|
|
|
|
The module defines the following and classes to represent IP addresses
|
|
and networks:
|
|
|
|
.. todo: list the properties and methods
|
|
|
|
.. class:: IPv4Address(address)
|
|
|
|
Construct an IPv4 address. *address* is a string or integer representing the
|
|
IP address. An :exc:`AddressValueError` is raised if *address* is not a
|
|
valid IPv4 address.
|
|
|
|
>>> ipaddress.IPv4Address('192.168.0.1')
|
|
IPv4Address('192.168.0.1')
|
|
>>> ipaddress.IPv4Address('192.0.2.1') == ipaddress.IPv4Address(3221225985)
|
|
True
|
|
|
|
|
|
.. class:: IPv4Interface(address)
|
|
|
|
Construct an IPv4 interface. *address* is a string or integer representing
|
|
the IP interface. An :exc:`AddressValueError` is raised if *address* is not
|
|
a valid IPv4 address.
|
|
|
|
The network address for the interface is determined by calling
|
|
``IPv4Network(address, strict=False)``.
|
|
|
|
>>> ipaddress.IPv4Interface('192.168.0.0/24')
|
|
IPv4Interface('192.168.0.0/24')
|
|
>>> ipaddress.IPv4Interface('192.168.0.0/24').network
|
|
IPv4Network('192.168.0.0/24')
|
|
|
|
|
|
.. 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.
|
|
|
|
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.
|
|
|
|
>>> 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')
|
|
|
|
|
|
.. class:: IPv6Address(address)
|
|
|
|
Construct an IPv6 address. *address* is a string or integer representing the
|
|
IP address. An :exc:`AddressValueError` is raised if *address* is not a
|
|
valid IPv6 address.
|
|
|
|
>>> ipaddress.IPv6Address('2001:db8::1000')
|
|
IPv6Address('2001:db8::1000')
|
|
|
|
|
|
.. class:: IPv6Interface(address)
|
|
|
|
Construct an IPv6 interface. *address* is a string or integer representing
|
|
the IP interface. An :exc:`AddressValueError` is raised if *address* is not
|
|
a valid IPv6 address.
|
|
|
|
The network address for the interface is determined by calling
|
|
``IPv6Network(address, strict=False)``.
|
|
|
|
>>> ipaddress.IPv6Interface('2001:db8::1000/96')
|
|
IPv6Interface('2001:db8::1000/96')
|
|
>>> ipaddress.IPv6Interface('2001:db8::1000/96').network
|
|
IPv6Network('2001:db8::/96')
|
|
|
|
|
|
.. 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.
|
|
|
|
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.
|
|
|
|
>>> 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')
|
|
|
|
|
|
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.
|