### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1c1 documentation »
- The Python Standard Library »
- 20. Internet Protocols and Support »

# 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.
  `is_link_local`
    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’)

    Note

    To sort networks with `sorted()`, `min()`, `max()` and other tools with a key argument, use the `operator.attrgetter()` function to extract the relevant fields:

        >>> from operator import attrgetter
        >>> s = [IPv6('::1/128'), IPv4('255.255.255.0/24')]
        >>> sorted(s, key=attrgetter('version', 'network', 'netmask'))
        [IPv4('255.255.255.0/24'), IPv6('::1/128')]

  `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.

### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1c1 documentation »
- The Python Standard Library »
- 20. Internet Protocols and Support »