python-peps/pep-3144.txt

210 lines
6.7 KiB
Plaintext
Raw Normal View History

PEP: 3144
Title: IP Address Manipulation Library for the Python Standard Library
Version: $Revision$
Last-Modified: $Date$
Author: Peter Moody <pmoody@google.com>
BDFL-Delegate: Nick Coghlan
Discussions-To: <ipaddr-py-dev@googlegroups.com>
2012-08-19 20:26:02 -04:00
Status: Final
Type: Standards Track
2017-01-24 15:47:22 -05:00
Content-Type: text/x-rst
Created: 6-Feb-2012
Python-Version: 3.3
Resolution: http://mail.python.org/pipermail/python-dev/2012-May/119474.html
2017-01-24 15:47:22 -05:00
Abstract
========
2017-01-24 15:47:22 -05:00
This PEP proposes a design and for an IP address manipulation module for
python.
2017-01-24 15:47:22 -05:00
PEP Acceptance
==============
2017-01-24 15:47:22 -05:00
This PEP was accepted by Nick Coghlan on the 15th of May, 2012.
2017-01-24 15:47:22 -05:00
Motivation
==========
2017-01-24 15:47:22 -05:00
Several very good IP address modules for python already exist.
The truth is that all of them struggle with the balance between
adherence to Pythonic principals and the shorthand upon which
network engineers and administrators rely. ipaddress aims to
strike the right balance.
2017-01-24 15:47:22 -05:00
Rationale
=========
2009-08-20 15:56:05 -04:00
2017-01-24 15:47:22 -05:00
The existence of several Python IP address manipulation modules is
evidence of an outstanding need for the functionality this module
seeks to provide.
2009-08-20 15:56:05 -04:00
2017-01-24 15:47:22 -05:00
Background
==========
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
PEP 3144 and ipaddr have been up for inclusion before. The
version of the library specified here is backwards incompatible
with the version on PyPI and the one which was discussed before.
In order to avoid confusing users of the current ipaddr, I've
renamed this version of the library "ipaddress".
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
The main differences between ipaddr and ipaddress are:
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
* ipaddress \*Network classes are equivalent to the ipaddr \*Network
class counterparts with the strict flag set to True.
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
* ipaddress \*Interface classes are equivalent to the ipaddr
\*Network class counterparts with the strict flag set to False.
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
* The factory functions in ipaddress were renamed to disambiguate
them from classes.
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
* A few attributes were renamed to disambiguate their purpose as
well. (eg. network, network_address)
2012-05-14 10:25:14 -04:00
2017-01-24 15:47:22 -05:00
* A number of methods and functions which returned containers in ipaddr now
return iterators. This includes, subnets, address_exclude,
summarize_address_range and collapse_address_list.
2012-05-14 10:25:14 -04:00
2012-05-10 11:22:13 -04:00
2017-01-24 15:47:22 -05:00
Due to the backwards incompatible API changes between ipaddress and ipaddr,
the proposal is to add the module using the new provisional API status:
2012-05-10 11:22:13 -04:00
2017-01-24 15:47:22 -05:00
* http://docs.python.org/dev/glossary.html#term-provisional-package
2012-05-10 11:22:13 -04:00
2017-01-24 15:47:22 -05:00
Relevant messages on python-dev:
2012-05-10 11:22:13 -04:00
2017-01-24 15:47:22 -05:00
* http://mail.python.org/pipermail/python-dev/2012-January/116016.html
* http://mail.python.org/pipermail/python-dev/2012-February/116656.html
* http://mail.python.org/pipermail/python-dev/2012-February/116688.html
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
Specification
=============
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
The ipaddr module defines a total of 6 new public classes, 3 for
manipulating IPv4 objects and 3 for manipulating IPv6 objects.
The classes are as follows:
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
- IPv4Address/IPv6Address - These define individual addresses, for
example the IPv4 address returned by an A record query for
www.google.com (74.125.224.84) or the IPv6 address returned by a
AAAA record query for ipv6.google.com (2001:4860:4001:801::1011).
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
- IPv4Network/IPv6Network - These define networks or groups of
addresses, 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).
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
- IPv4Interface/IPv6Interface - These hybrid classes refer to an
individual address on a given network. For example, the IPV4
address 192.0.2.1 on the network 192.0.2.0/24 could be referred to
as 192.0.2.1/24. Likewise, the IPv6 address 2001:DB8::1 on the
network 2001:DB8::/96 could be referred to as 2001:DB8::1/96.
It's very common to refer to addresses assigned to computer
network interfaces like this, hence the Interface name.
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
All IPv4 classes share certain characteristics and methods; the
number of bits needed to represent them, whether or not they
belong to certain special IPv4 network ranges, etc. Similarly,
all IPv6 classes share characteristics and methods.
2009-08-27 18:51:15 -04:00
2017-01-24 15:47:22 -05:00
ipaddr makes extensive use of inheritance to avoid code
duplication as much as possible. The parent classes are private,
but they are outlined here:
2009-08-20 15:56:05 -04:00
2017-01-24 15:47:22 -05:00
- _IPAddrBase - Provides methods common to all ipaddr objects.
2009-08-20 15:56:05 -04:00
2017-01-24 15:47:22 -05:00
- _BaseAddress - Provides methods common to IPv4Address and
IPv6Address.
2009-08-20 15:56:05 -04:00
2017-01-24 15:47:22 -05:00
- _BaseInterface - Provides methods common to IPv4Interface and
IPv6Interface, as well as IPv4Network and IPv6Network (ipaddr
treats the Network classes as a special case of Interface).
2009-08-20 15:56:05 -04:00
2017-01-24 15:47:22 -05:00
- _BaseV4 - Provides methods and variables (eg, _max_prefixlen)
common to all IPv4 classes.
2009-08-20 15:56:05 -04:00
2017-01-24 15:47:22 -05:00
- _BaseV6 - Provides methods and variables common to all IPv6 classes.
2009-08-20 15:56:05 -04:00
2017-01-24 15:47:22 -05:00
Comparisons between objects of differing IP versions results in a
``TypeError`` [1]_. Additionally, comparisons of objects with
different _Base parent classes results in a ``TypeError``. The effect
of the _Base parent class limitation is that IPv4Interface's can
be compared to IPv4Network's and IPv6Interface's can be compared
to IPv6Network's.
2017-01-24 15:47:22 -05:00
Reference Implementation
========================
2012-05-10 11:22:13 -04:00
2017-01-24 15:47:22 -05:00
The current reference implementation can be found at:
2017-01-24 15:47:22 -05:00
http://code.google.com/p/ipaddress-py/source/browse/ipaddress.py
2017-01-24 15:47:22 -05:00
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
2017-01-24 15:47:22 -05:00
More information about using the reference implementation can be
found at: http://code.google.com/p/ipaddr-py/wiki/Using3144
2017-01-24 15:47:22 -05:00
References
==========
2009-09-27 15:38:05 -04:00
2017-01-24 15:47:22 -05:00
.. [1] Appealing to authority is a logical fallacy, but Vint Cerf is an
authority who can't be ignored. Full text of the email
follows:
2009-09-27 15:38:05 -04:00
2017-01-24 15:47:22 -05:00
"""
I have seen a substantial amount of traffic about IPv4 and
IPv6 comparisons and the general consensus is that these are
not comparable.
2009-09-27 15:38:05 -04:00
2017-01-24 15:47:22 -05:00
If we were to take a very simple minded view, we might treat
these as pure integers in which case there is an ordering but
not a useful one.
2009-09-27 15:38:05 -04:00
2017-01-24 15:47:22 -05:00
In the IPv4 world, "length" is important because we take
longest (most specific) address first for routing. Length is
determine by the mask, as you know.
2009-09-27 15:38:05 -04:00
2017-01-24 15:47:22 -05:00
Assuming that the same style of argument works in IPv6, we
would have to conclude that treating an IPv6 value purely as
an integer for comparison with IPv4 would lead to some really
strange results.
2009-09-27 15:38:05 -04:00
2017-01-24 15:47:22 -05:00
All of IPv4 space would lie in the host space of 0::0/96
prefix of IPv6. For any useful interpretation of IPv4, this is
a non-starter.
2009-09-27 15:38:05 -04:00
2017-01-24 15:47:22 -05:00
I think the only sensible conclusion is that IPv4 values and
IPv6 values should be treated as non-comparable.
2017-01-24 15:47:22 -05:00
Vint
"""
2017-01-24 15:47:22 -05:00
Copyright
=========
2017-01-24 15:47:22 -05:00
This document has been placed in the public domain.
2017-01-24 15:47:22 -05:00
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End: