Abstract

This PEP proposes a design and for an IP address manipulation module forpython.

PEP Acceptance

This PEP was accepted by Alyssa Coghlan on the 15th of May, 2012.

Motivation

Several very good IP address modules for python already exist.The truth is that all of them struggle with the balance betweenadherence to Pythonic principals and the shorthand upon whichnetwork engineers and administrators rely.ipaddress aims tostrike the right balance.

Rationale

The existence of several Python IP address manipulation modules isevidence of an outstanding need for the functionality this moduleseeks to provide.

Background

PEP 3144 andipaddr have been up for inclusion before. Theversion of the library specified here is backwards incompatiblewith the version on PyPI and the one which was discussed before.In order to avoid confusing users of the currentipaddr, I’verenamed this version of the libraryipaddress.

The main differences between ipaddr and ipaddress are:

• ipaddress *Network classes are equivalent to theipaddr *Networkclass counterparts with thestrict flag set toTrue.
• ipaddress *Interface classes are equivalent to theipaddr*Network class counterparts with thestrict flag set toFalse.
• The factory functions inipaddress were renamed to disambiguatethem from classes.
• A few attributes were renamed to disambiguate their purpose aswell. (eg.network,network_address)
• A number of methods and functions which returned containers inipaddr nowreturn iterators. This includessubnets,address_exclude,summarize_address_range andcollapse_address_list.

Due to the backwards incompatible API changes betweenipaddress andipaddr,the proposal is to add the module using the new provisional API status:

• http://docs.python.org/dev/glossary.html#term-provisional-package

Relevant messages on python-dev:

• https://mail.python.org/pipermail/python-dev/2012-January/116016.html
• https://mail.python.org/pipermail/python-dev/2012-February/116656.html
• https://mail.python.org/pipermail/python-dev/2012-February/116688.html

Specification

Theipaddr module defines a total of 6 new public classes, 3 formanipulating IPv4 objects and 3 for manipulating IPv6 objects.The classes are as follows:

• IPv4Address/IPv6Address - These define individual addresses, forexample the IPv4 address returned by an A record query forwww.google.com (74.125.224.84) or the IPv6 address returned by aAAAA record query for ipv6.google.com (2001:4860:4001:801::1011).
• IPv4Network/IPv6Network - These define networks or groups ofaddresses, for example the IPv4 network reserved for multicast use(224.0.0.0/4) or the IPv6 network reserved for multicast(ff00::/8, wow, that’s big).
• IPv4Interface/IPv6Interface - These hybrid classes refer to anindividual address on a given network. For example, the IPV4address 192.0.2.1 on the network 192.0.2.0/24 could be referred toas 192.0.2.1/24. Likewise, the IPv6 address 2001:DB8::1 on thenetwork 2001:DB8::/96 could be referred to as 2001:DB8::1/96.It’s very common to refer to addresses assigned to computernetwork interfaces like this, hence the Interface name.

All IPv4 classes share certain characteristics and methods; thenumber of bits needed to represent them, whether or not theybelong to certain special IPv4 network ranges, etc. Similarly,all IPv6 classes share characteristics and methods.

ipaddr makes extensive use of inheritance to avoid codeduplication as much as possible. The parent classes are private,but they are outlined here:

• _IPAddrBase - Provides methods common to allipaddr objects.
• _BaseAddress - Provides methods common toIPv4Address andIPv6Address.
• _BaseInterface - Provides methods common toIPv4Interface andIPv6Interface, as well asIPv4Network andIPv6Network (ipaddrtreats the Network classes as a special case of Interface).
• _BaseV4 - Provides methods and variables (eg,_max_prefixlen)common to all IPv4 classes.
• _BaseV6 - Provides methods and variables common to all IPv6 classes.

Comparisons between objects of differing IP versions results in aTypeError[1]. Additionally, comparisons of objects withdifferent _Base parent classes results in aTypeError. The effectof the _Base parent class limitation is thatIPv4Interface’s canbe compared toIPv4Network’s andIPv6Interface’s can be comparedtoIPv6Network’s.

Reference Implementation

The current reference implementation can be found at:

http://code.google.com/p/ipaddress-py/source/browse/ipaddress.py

Or see the tarball to include the README and unittests.http://code.google.com/p/ipaddress-py/downloads/detail?name=ipaddress-1.0.tar.gz

More information about using the reference implementation can befound at:http://code.google.com/p/ipaddr-py/wiki/Using3144

References

Copyright

This document has been placed in the public domain.