.. _ipaddress-howto:
***************************************
-An Introduction to the ipaddress module
+An introduction to the ipaddress module
***************************************
:author: Peter Moody
when working with IP addressing. The simplest way to create addresses is
to use the :func:`ipaddress.ip_address` factory function, which automatically
determines whether to create an IPv4 or IPv6 address based on the passed in
-value::
+value:
+
+.. testsetup::
+ >>> import ipaddress
+
+::
>>> ipaddress.ip_address('192.0.2.1')
IPv4Address('192.0.2.1')
>>> ipaddress.ip_interface('192.0.2.1/24')
IPv4Interface('192.0.2.1/24')
- >>> ipaddress.ip_network('2001:db8::1/96')
+ >>> ipaddress.ip_interface('2001:db8::1/96')
IPv6Interface('2001:db8::1/96')
Integer inputs are accepted (as with networks), and use of a particular IP
Finding out how many individual addresses are in a network::
>>> net4 = ipaddress.ip_network('192.0.2.0/24')
- >>> net4.numhosts
+ >>> net4.num_addresses
256
>>> net6 = ipaddress.ip_network('2001:db8::0/96')
- >>> net6.numhosts
+ >>> net6.num_addresses
4294967296
Iterating through the "usable" addresses on a network::
>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> for x in net4.hosts():
- print(x)
+ ... print(x) # doctest: +ELLIPSIS
192.0.2.1
192.0.2.2
192.0.2.3
192.0.2.4
- <snip>
+ ...
192.0.2.252
192.0.2.253
192.0.2.254
Exploding or compressing the address::
>>> addr6.exploded
- '2001:0db8:0000:0000:0000:0000:0000:0000'
+ '2001:0db8:0000:0000:0000:0000:0000:0001'
>>> addr6.compressed
- '2001:db8::'
+ '2001:db8::1'
>>> net6.exploded
'2001:0db8:0000:0000:0000:0000:0000:0000/96'
>>> net6.compressed
>>> net4[-1]
IPv4Address('192.0.2.255')
>>> net6[1]
- IPv6Address('2001::1')
+ IPv6Address('2001:db8::1')
>>> net6[-1]
- IPv6Address('2001::ffff:ffff')
+ IPv6Address('2001:db8::ffff:ffff')
It also means that network objects lend themselves to using the list
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.
+ 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.IPv4Address('192.168.0.1')
IPv4Address('192.168.0.1')
- >>> ipaddress.IPv4Address(3221225985)
+ >>> ipaddress.IPv4Address(3232235521)
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01')
IPv4Address('192.168.0.1')
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())
+ >>> 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')]
>>> n1 = ip_network('192.0.2.0/28')
>>> n2 = ip_network('192.0.2.1/32')
- >>> list(n1.address_exclude(n2))
+ >>> 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')]
>>> 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))
+ >>> 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))
+ >>> 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))
"""Summarize a network range given the first and last IP addresses.
Example:
- >>> summarize_address_range(IPv4Address('192.0.2.0'),
- IPv4Address('192.0.2.130'))
+ >>> list(summarize_address_range(IPv4Address('192.0.2.0'),
+ ... IPv4Address('192.0.2.130')))
+ ... #doctest: +NORMALIZE_WHITESPACE
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'),
- IPv4Network('192.0.2.130/32')]
+ IPv4Network('192.0.2.130/32')]
Args:
first: the first IPv4Address or IPv6Address in the range.