Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity
cpython/Doc/library/ipaddr.rst

418 lines
11 KiB
ReStructuredText
Raw Blame History

:mod:`ipaddr` --- IP address manipulation library
=================================================
.. module:: ipaddr
:synopsis: IPv4 and IPv6 network address manipulation classes.
.. moduleauthor:: Google, Inc.
.. sectionauthor:: Gregory P. Smith <greg@krypto.org>
.. versionadded:: 2.7
.. index::
single: IP address, IPv4, IPv6, netmask
This module implements classes for working with IP host and network addresses,
both IPv4 and IPv6.
.. _ipaddr_examples:
Examples
--------
Netmask.
>>> ipaddr.IP('1.1.1.1/255.255.255.0')
IPv4('1.1.1.1/24')
>>> ipaddr.IP('1080::200C:417B/96')
IPv6('1080::200c:417b/96')
Hostmask.
>>> ipaddr.IPv4('1.1.1.1/0.0.0.255')
IPv4('1.1.1.1/24')
Prefix length.
>>> addr = ipaddr.IPv4('1.1.1.1/24')
>>> addr.prefixlen
24
Individual addresses.
>>> ipaddr.IP('1.1.1.1')
IPv4('1.1.1.1/32')
Many standard Python operations are also supported.
Comparison.
>>> ipaddr.IPv4('1.1.1.1') == ipaddr.IPv4('1.1.1.2')
False
>>> ipaddr.IPv4('1.1.1.1') < ipaddr.IPv4('1.1.1.2')
True
Inclusion.
>>> ipaddr.IPv4('1.1.1.1') in ipaddr.IPv4("1.0.0.0/8")
True
Sorting.
>>> a = ipaddr.IPv4('1.1.1.10')
>>> b = ipaddr.IPv4('1.10.1.10')
>>> c = ipaddr.IPv4('1.1.10.10')
>>> d = ipaddr.IPv4('1.1.1.1')
>>> sorted([a, b, c, d])
[IPv4('1.1.1.1/32'), IPv4('1.1.1.10/32'), IPv4('1.1.10.10/32'), IPv4('1.10.1.10/32')]
Conversion to string and integer forms.
>>> spam = ipaddr.IPv4('192.168.1.254'))
>>> str(spam)
'192.168.1.254/32'
>>> spam.ip_ext
'192.168.1.254'
>>> int(spam)
3232236030
>>> eggs = ipaddr.IPv6('ffff::1/120')
>>> int(eggs)
340277174624079928635746076935438991361
Additionally, there are quite a few network-specific features available to
ipaddr.
>>> ipaddr.IPv4('10.0.0.0/8').supernet()
IPv4('10.0.0.0/7')
>>> ipaddr.IPv4('10.0.0.0/8').subnet()
[IPv4('10.0.0.0/9'), IPv4('10.128.0.0/9')]
# This returns networks with a prefix length of /10
>>> ipaddr.IPv4('10.0.0.0/8').subnet(prefixlen_diff=2)
[IPv4('10.0.0.0/10'), IPv4('10.64.0.0/10'), IPv4('10.128.0.0/10'), IPv4('10.192.0.0/10')]
# Remove an address from a superblock.
>>> ipaddr.IP('10.0.0.0/24').address_exclude(ipaddr.IP('10.0.0.0/28'))
[IPv4('10.0.0.16/28'), IPv4('10.0.0.32/27'), IPv4('10.0.0.64/26'), IPv4('10.0.0.128/25')]
.. _ipaddr_funcs_and_classes:
Functions And Classes
---------------------
.. function:: IP(ipaddr)
Take an IP string or int and return an object of the correct type. Returns
an :class:`IPv4` or :class:`IPv6` object.
The *ipaddr* parameter must be 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.
Raises :exc:`ValueError` if the *ipaddr* passed is not either an IPv4 or an
IPv6 address.
.. function:: collapse_address_list(addresses)
Collapse a sequence of :class:`IPv4` or :class:`IPv6` objects into the most
concise representation. Returns a list of :class:`IPv4` or :class:`IPv6`
objects.
Example usage::
>>> collapse_address_list([IPv4('1.1.0.0/24'), IPv4('1.1.1.0/24')])
[IPv4('1.1.0.0/23')]
.. class:: BaseIP()
A generic IP address object. This base class defines the API and contains
common code. Most authors should either use the :func:`IP` function or
create :class:`IPv4` or :class:`IPv6` objects directly rather than using this
base class.
IP address objects support the following python operators:
``=``, ``!=``, ``<``, ``>``, ``<=``, ``>=``, and ``in``.
An IP address object may be used as a sequence index or as a hash key and can
be converted back to an integer representation using :func:`int`. It may
also be used as a sequence that yields the string representation of every IP
address within the object's subnet.
The following properties are available on all IP address objects:
.. attribute:: broadcast
Integer representation of the broadcast address. Read only.
.. attribute:: broadcast_ext
Dotted decimal or colon string version of the broadcast address. Read
only.
.. attribute:: hostmask
Integer representation of the hostmask. Read only.
.. attribute:: hostmask_ext
Dotted decimal or colon string version of the hostmask. Read only.
.. attribute:: ip
Integer representation of the IP address. Read only.
.. attribute:: ip_ext
Dotted decimal or colon string version of the IP address. Read only.
.. attribute:: ip_ext_full
Canonical string version of the IP address. Read only.
.. attribute:: is_loopback
True if the address is a loopback address as defined in IPv4 :rfc:`3330`
or IPv6 :rfc:`2373` section 2.5.3.
.. attribute:: is_link_local
True if the address is a link-local address as defined in IPv4 :rfc:`3927`
or IPv6 :rfc:`4291`.
.. attribute:: is_multicast
True if the address is reserved for multicast use. See IPv4 :rfc:`3171`
or IPv6 :rfc:`2373` section 2.7 for details.
.. attribute:: is_private
True if the address is reserved for private networks as defined in IPv4
:rfc:`1918` or IPv6 :rfc:`4193`.
.. attribute:: netmask
Integer representation of the netmask. Read only.
.. attribute:: netmask_ext
Dotted decimal or colon string version of the netmask. Read only.
.. attribute:: network
Integer representation of the network. Read only.
.. attribute:: network_ext
Dotted decimal or colon string version of the network. Read only.
.. attribute:: numhosts
Number of hosts in the current subnet. Read only.
.. attribute:: packed
The packed network byte order representation of this network address.
Read only.
.. attribute:: prefixlen
A property to get and set the prefix length. Readable and writeable.
.. attribute:: version
Integer IP version number. Read only.
The following methods are available on all IP address objects:
.. method:: address_exclude(other)
Remove an address from within a larger block. Returns a sorted list of IP
address objects representing networks.
Examples::
>>> addr1 = IP('10.1.1.0/24')
>>> addr2 = IP('10.1.1.0/26')
>>> addr1.address_exclude(addr2)
[IP('10.1.1.64/26'), IP('10.1.1.128/25')]
>>> addr1 = IP('::1/32')
>>> addr2 = IP('::1/128')
>>> addr1.address_exclude(addr2)
[IP('::0/128'), IP('::2/127'), IP('::4/126'), IP('::8/125'), IP('0:0:8000::/33')]
Raises :exc:`ValueError` if *other* is not completely contained by *self*.
.. method:: compare_networks(other)
Compare this IP object's network to another IP network.
Returns -1, 0 or 1.
This compares the integer representation of the network addresses. The
host bits are not considered by this method. If you want to compare host
bits, you can use ``host_a.ip < host_b.ip``.
If the IP versions of self and other are the same, returns:
-1 if self < other
eg: IPv4('1.1.1.0/24') < IPv4('1.1.2.0/24')
IPv6('1080::200C:417A') < IPv6('1080::200B:417B')
0 if self == other
eg: IPv4('1.1.1.1/24') == IPv4('1.1.1.2/24')
IPv6('1080::200C:417A/96') == IPv6('1080::200C:417B/96')
1 if self > other
eg: IPv4('1.1.1.0/24') > IPv4('1.1.0.0/24')
IPv6('1080::1:200C:417A/112') > IPv6('1080::0:200C:417A/112')
If the IP versions of self and other are different, returns:
-1 if self.version < other.version
eg: IPv4('10.0.0.1/24') < IPv6('::1/128')
1 if self.version > other.version
eg: IPv6('::1/128') > IPv4('255.255.255.0/24')
.. method:: subnet(prefixlen_diff=1)
Returns a list of subnets which when joined make up the current subnet.
The optional *prefixlen_diff* argument specifies how many bits the prefix
length should be increased by. Given a /24 network and
``prefixlen_diff=3``, for example, 8 subnets of size /27 will be returned.
If called on a host IP address rather than a network, a list containing
the host itself will be returned.
Raises :exc:`PrefixlenDiffInvalidError` if the *prefixlen_diff* is out of
range.
.. method:: supernet(prefixlen_diff=1)
Returns a single IP object representing the supernet containing the
current network.
The optional *prefixlen_diff* argument specifies how many bits the prefix
length should be decreased by. Given a /24 network and
``prefixlen_diff=3``, for example, a supernet with a 21 bit netmask is
returned.
Raises :exc:`PrefixlenDiffInvalidError` if the prefixlen_diff is out of
range.
.. class:: IPv4()
This class represents and manipulates 32-bit IPv4 addresses.
Attributes::
# These examples for IPv4('1.2.3.4/27')
.ip: 16909060
.ip_ext: '1.2.3.4'
.ip_ext_full: '1.2.3.4'
.network: 16909056
.network_ext: '1.2.3.0'
.hostmask: 31 (0x1F)
.hostmask_ext: '0.0.0.31'
.broadcast: 16909087 (0x102031F)
.broadcast_ext: '1.2.3.31'
.netmask: 4294967040 (0xFFFFFFE0)
.netmask_ext: '255.255.255.224'
.prefixlen: 27
.. class:: IPv6()
This class respresents and manipulates 128-bit IPv6 addresses.
Attributes::
# These examples are for IPv6('2001:658:22A:CAFE:200::1/64')
.ip: 42540616829182469433547762482097946625
.ip_ext: '2001:658:22a:cafe:200::1'
.ip_ext_full: '2001:0658:022a:cafe:0200:0000:0000:0001'
.network: 42540616829182469433403647294022090752
.network_ext: '2001:658:22a:cafe::'
.hostmask: 18446744073709551615
.hostmask_ext: '::ffff:ffff:ffff:ffff'
.broadcast: 42540616829182469451850391367731642367
.broadcast_ext: '2001:658:22a:cafe:ffff:ffff:ffff:ffff'
.netmask: 340282366920938463444927863358058659840
.netmask_ext: 64
.prefixlen: 64
.. attribute:: is_site_local
True if the address was reserved as site-local in :rfc:`3513` section
2.5.6.
.. note::
The IPv6 site-local address space has been deprecated by :rfc:`3879`.
Use :data:`is_private` to test if this address is in the space of
unique local addresses as defined by :rfc:`4193`.
.. attribute:: is_unspecified
True if this is the unspecified address as defined in :rfc:`2373` section
2.5.2.
.. _ipaddr_exceptions:
Exceptions
----------
The following exceptions are defined by this module:
.. exception:: Error
Base class for all exceptions defined in this module.
.. exception:: IPTypeError
Tried to perform a v4 action on v6 object or vice versa.
.. exception:: IPAddressExclusionError
An Error we should never see occurred in address exclusion.
.. exception:: IPv4IpValidationError
Raised when an IPv4 address is invalid.
.. exception:: IPv4NetmaskValidationError
Raised when a netmask is invalid.
.. exception:: IPv6IpValidationError
Raised when an IPv6 address is invalid.
.. exception:: IPv6NetmaskValidationError
Raised when an IPv6 netmask is invalid.
.. exception:: PrefixlenDiffInvalidError
Raised when :meth:`BaseIP.subnet` or :meth:`BaseIP.supernet` is called with a
bad ``prefixlen_diff``.
.. seealso::
http://code.google.com/p/ipaddr-py/
The original source of this module and a place to download it as a package
for use on earlier versions of Python.
Reference in New Issue View Git Blame Copy Permalink