20.19. ipaddr — IP address manipulation library

New in version 3.1.

This module implements classes for working with IP host and network addresses, both IPv4 and IPv6.

ipaddr.IP(ipaddr)

Take an IP string or int and return an object of the correct type. Returns an IPv4 or IPv6 object.

The ipaddr parameter must be a string, bytes or integer representing the IP address in ascii, network byte order or as a number respectively. Either IPv4 or IPv6 addresses may be supplied. Integers less than 2**32 will be considered to be IPv4.

Raises ValueError if the ipaddr passed is not either an IPv4 or an IPv6 address.

ipaddr.collapse_address_list(addresses)

Collapse a sequence of IPv4 or IPv6 objects into the most concise representation. Returns a list of IPv4 or 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 ipaddr.BaseIP

A generic IP address object. This base class defines the API and contains common code. Most authors should either use the IP() function or create IPv4 or 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 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:

broadcast
Integer representation of the broadcast address. Read only.
broadcast_ext
Dotted decimal or colon string version of the broadcast address. Read only.
hostmask
Integer representation of the hostmask. Read only.
hostmask_ext
Dotted decimal or colon string version of the hostmask. Read only.
ip
Integer representation of the IP address. Read only.
ip_ext
Dotted decimal or colon string version of the IP address. Read only.
ip_ext_full
Canonical string version of the IP address. Read only.
is_loopback
True if the address is a loopback address as defined in IPv4 RFC 3330 or IPv6 RFC 2373 section 2.5.3.
True if the address is a link-local address as defined in IPv4 RFC 3927 or IPv6 RFC 4291.
is_multicast
True if the address is reserved for multicast use. See IPv4 RFC 3171 or IPv6 RFC 2373 section 2.7 for details.
is_private
True if the address is reserved for private networks as defined in IPv4 RFC 1918 or IPv6 RFC 4193.
netmask
Integer representation of the netmask. Read only.
netmask_ext
Dotted decimal or colon string version of the netmask. Read only.
network
Integer representation of the network. Read only.
network_ext
Dotted decimal or colon string version of the network. Read only.
numhosts
Number of hosts in the current subnet. Read only.
packed
The packed network byte order representation of this network address. Read only.
prefixlen
A property to get and set the prefix length. Readable and writeable.
version
Integer IP version number. Read only.

The following methods are available on all IP address objects:

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 ValueError if other is not completely contained by self.

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’)
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 PrefixlenDiffInvalidError if the prefixlen_diff is out of range.

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 PrefixlenDiffInvalidError if the prefixlen_diff is out of range.

class ipaddr.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 ipaddr.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
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 is_private to test if this address is in the space of unique local addresses as defined by RFC 4193.

is_unspecified
True if this is the unspecified address as defined in RFC 2373 section 2.5.2.

The following exceptions are defined by this module:

exception ipaddr.Error
Base class for all exceptions defined in this module.
exception ipaddr.IPTypeError
Tried to perform a v4 action on v6 object or vice versa.
exception ipaddr.IPAddressExclusionError
An Error we should never see occurred in address exclusion.
exception ipaddr.IPv4IpValidationError
Raised when an IPv4 address is invalid.
exception ipaddr.IPv4NetmaskValidationError
Raised when a netmask is invalid.
exception ipaddr.IPv6IpValidationError
Raised when an IPv6 address is invalid.
exception ipaddr.IPv6NetmaskValidationError
Raised when an IPv6 netmask is invalid.
exception ipaddr.PrefixlenDiffInvalidError
Raised when BaseIP.subnet() or BaseIP.supernet() is called with a bad prefixlen_diff.

See also

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.

Previous topic

20.18. uuid — UUID objects according to RFC 4122

Next topic

20.20. socketserver — A framework for network servers

This Page