cpython: cacf3b1e20da (original) (raw)
Mercurial > cpython
changeset 77479:cacf3b1e20da
Issue #14814: Add first draft of PEP 3144 ipaddress module documentation (initial patch by Sandro Tosi) [#14814]
| Nick Coghlan ncoghlan@gmail.com | |
|---|---|
| date | Sun, 17 Jun 2012 17:24:10 +1000 |
| parents | 739f5c725958 |
| children | afe67ea94bc6 |
| files | Doc/howto/ipaddress.rst Doc/library/internet.rst Doc/library/ipaddress.rst Misc/NEWS |
| diffstat | 4 files changed, 278 insertions(+), 13 deletions(-)[+] [-] Doc/howto/ipaddress.rst 34 Doc/library/internet.rst 1 Doc/library/ipaddress.rst 251 Misc/NEWS 5 |
line wrap: on
line diff
--- a/Doc/howto/ipaddress.rst +++ b/Doc/howto/ipaddress.rst @@ -1,14 +1,19 @@ .. _ipaddress-howto: - -Ipaddress Howto - + +An Introduction to the ipaddress module + :author: Peter Moody +:author: Nick Coghlan -.. topic:: Abstract +.. topic:: Overview
- This document aims to provide a gentle introduction to :mod:
ipaddress - module. It is aimed primarily at users that aren't already familiar with
- IP networking terminology, but may also be useful to network engineers
- wanting an overview of how the ipaddress module represents IP network
- addressing concepts.
Creating Address/Network/Interface objects
@@ -40,7 +45,7 @@ IP Host Addresses
Addresses, often referred to as "host addresses" are the most basic unit
when working with IP addressing. The simplest way to create addresses is
-to use the ip_address factory function, which automatically determines
+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::
>>> ipaddress.ip_address('192.0.2.1')
@@ -113,7 +118,7 @@ integer, so the network prefix includes
>>> ipaddress.ip_network(3221225984)
IPv4Network('192.0.2.0/32')
Creation of a particular kind of network can be forced by calling the
@@ -275,15 +280,18 @@ an integer or string that the other modu
Exceptions raised by :mod:ipaddress
=====================================
-If you try to create an address/network/interface object with an invalid value
-for either the address or netmask, :mod:ipaddress will raise an
-:exc:AddressValueError or :exc:NetmaskValueError respectively. However,
-this applies only when calling the class constructors directly. The factory
-functions and other module level functions will just raise :exc:ValueError.
+When creating address/network/interface objects using the version-agnostic
+factory functions, any errors will be reported as :exc:ValueError.
+
+For some use cases, it desirable to know whether it is the address or the
+netmask which is incorrect. To support these use cases, the class
+constructors actually raise the :exc:ValueError subclasses
+:exc:ipaddress.AddressValueError and :exc:ipaddress.NetmaskValueError
+to indicate exactly which part of the definition failed to parse correctly.
Both of the module specific exceptions have :exc:ValueError as their
parent class, so if you're not concerned with the particular type of error,
-you can still do the following::
+you can still write code like the following::
try:
ipaddress.IPv4Address(address)
--- a/Doc/library/internet.rst +++ b/Doc/library/internet.rst @@ -42,3 +42,4 @@ is currently supported on most popular p http.cookiejar.rst xmlrpc.client.rst xmlrpc.server.rst
new file mode 100644
--- /dev/null
+++ b/Doc/library/ipaddress.rst
@@ -0,0 +1,251 @@
+:mod:ipaddress --- IPv4/IPv6 manipulation library
+===================================================
+
+.. module:: ipaddress
+Source code: :source:Lib/ipaddress.py
+
+--------------
+
+The :mod:ipaddress module provides the capabilities to create, manipulate and
+operate on IPv4 and IPv6 addresses and networks.
+
+This is the full module API reference - for an overview and introduction,
+see :ref:ipaddress-howto.
+
+The functions and classes in this module make it straightforward to handle
+various tasks related to IP addresses, including checking whether or not two
+hosts are on the same subnet, iterating over all hosts in a particular
+subnet, as well as checking whether or not a string represents a valid
+IP address or network definition.
+
+
+Defining IP Addresses and Interfaces
+------------------------------------
+
+The :mod:ipaddress module provides factory functions to define IP addresses
+and networks:
+
+.. function:: ip_address(address)
+
- Return an :class:
IPv4Addressor :class:IPv6Addressobject depending on - the IP address passed as argument. address is a string or integer
- representing the IP address. Either IPv4 or IPv6 addresses may be supplied;
- integers less than 2**32 will be considered to be IPv4 by default. A
- :exc:
ValueErroris raised if the address passed is neither an IPv4 nor - IPv6 address. +
- IPv4Address('192.168.0.1')
- IPv6Address('2001:db8::') +
+ +.. function:: ip_network(address, strict=True) +
- Return an :class:
IPv4Networkor :class:IPv6Networkobject depending on - the IP address passed as argument. address is a string or integer
- representing the IP network. Either IPv4 or IPv6 networks may be supplied;
- integers less than 2**32 will be considered to be IPv4 by default. strict
- is passed to :class:
IPv4Networkor :class:IPv6Networkconstructor. A - :exc:
ValueErroris raised if the string passed isn't either an IPv4 or IPv6 - address, or if the network has host bits set. +
- IPv4Network('192.168.0.0/28') +
+ +.. function:: ip_interface(address) +
- Return an :class:
IPv4Interfaceor :class:IPv6Interfaceobject depending - on the IP address passed as argument. address is a string or integer
- representing the IP address. Either IPv4 or IPv6 addresses may be supplied;
- integers less than 2**32 will be considered to be IPv4 by default.. A
- :exc:
ValueErroris raised if the address passed isn't either an IPv4 or - IPv6 address. +
+ +Representing IP Addresses and Networks +-------------------------------------- + +The module defines the following and classes to represent IP addresses +and networks: + +.. todo: list the properties and methods + +.. class:: IPv4Address(address) +
- Construct an IPv4 address. address is a string or integer representing the
- IP address. An :exc:
AddressValueErroris raised if address is not a - valid IPv4 address. +
- IPv4Address('192.168.0.1')
ipaddress.IPv4Address('192.0.2.1') == ipaddress.IPv4Address(3221225985)
- True +
+ +.. class:: IPv4Interface(address) +
- Construct an IPv4 interface. address is a string or integer representing
- the IP interface. An :exc:
AddressValueErroris raised if address is not - a valid IPv4 address. +
- The network address for the interface is determined by calling
IPv4Network(address, strict=False). +- IPv4Interface('192.168.0.0/24')
- IPv4Network('192.168.0.0/24') +
+ +.. class:: IPv4Network(address, strict=True) +
- Construct an IPv4 network. address is a string or integer representing the
- IP address (and optionally the network). An :exc:
AddressValueErroris - raised if address is not a valid IPv4 address. A :exc:
NetmaskValueError - is raised if the netmask is not valid for an IPv4 address. +
- If strict is
Trueand host bits are set in the supplied address, - then :exc:
ValueErroris raised. Otherwise, the host bits are masked out - to determine the appropriate network address. +
- IPv4Network('192.0.2.0/27')
- IPv4Address('255.255.255.224')
- IPv4Network('192.0.2.0/27') +
+ +.. class:: IPv6Address(address) +
- Construct an IPv6 address. address is a string or integer representing the
- IP address. An :exc:
AddressValueErroris raised if address is not a - valid IPv6 address. +
- IPv6Address('2001:db8::1000') +
+ +.. class:: IPv6Interface(address) +
- Construct an IPv6 interface. address is a string or integer representing
- the IP interface. An :exc:
AddressValueErroris raised if address is not - a valid IPv6 address. +
- The network address for the interface is determined by calling
IPv6Network(address, strict=False). +- IPv6Interface('2001:db8::1000/96')
- IPv6Network('2001:db8::/96') +
+ +.. class:: IPv6Network(address, strict=True) +
- Construct an IPv6 network. address is a string or integer representing the
- IP address (and optionally the network). An :exc:
AddressValueErroris - raised if address is not a valid IPv6 address. A :exc:
NetmaskValueError - is raised if the netmask is not valid for an IPv6 address. +
- If strict is
Trueand host bits are set in the supplied address, - then :exc:
ValueErroris raised. Otherwise, the host bits are masked out - to determine the appropriate network address. +
- IPv6Network('2001:db8::/96')
- IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::')
- IPv6Network('2001:db8::/96') +
+ +Other Module Level Functions +---------------------------- + +The module also provides the following module level functions: + +.. function:: v4_int_to_packed(address) +
- Represent an address as 4 packed bytes in network (big-endian) order.
- address is an integer representation of an IPv4 IP address. A
- :exc:
ValueErroris raised if the integer is negative or too large to be an - IPv4 IP address. +
- IPv4Address('192.0.2.1')
- b'\xc0\x00\x02\x01' +
+ +.. function:: v6_int_to_packed(address) +
- Represent an address as 16 packed bytes in network (big-endian) order.
- address is an integer representation of an IPv6 IP address. A
- :exc:
ValueErroris raised if the integer is negative or too large to be an - IPv6 IP address. +
+ +.. function:: summarize_address_range(first, last) +
- Return an iterator of the summarized network range given the first and last
- IP addresses. first is the first :class:
IPv4Addressor - :class:
IPv6Addressin the range and last is the last :class:IPv4Address - or :class:
IPv6Addressin the range. A :exc:TypeErroris raised if - first or last are not IP addresses or are not of the same version. A
- :exc:
ValueErroris raised if last is not greater than first or if - first address version is not 4 or 6. +
- ... ipaddress.IPv4Address('192.0.2.0'),
- ... ipaddress.IPv4Address('192.0.2.130'))]
- [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')] +
+ +.. function:: collapse_addresses(addresses) +
- Return an iterator of the collapsed :class:
IPv4Networkor - :class:
IPv6Networkobjects. addresses is an iterator of - :class:
IPv4Networkor :class:IPv6Networkobjects. A :exc:TypeErroris - raised if addresses contains mixed version objects. +
- ... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'),
- ... ipaddress.IPv4Network('192.0.2.128/25')])]
- [IPv4Network('192.0.2.0/24')] +
+ +.. function:: get_mixed_type_key(obj) +
- Return a key suitable for sorting between networks and addresses. Address
- and Network objects are not sortable by default; they're fundamentally
- different, so the expression:: +
IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')[](#l3.233)
- doesn't make sense. There are some times however, where you may wish to
- have :mod:
ipaddresssort these anyway. If you need to do this, you can use - this function as the
keyargument to :func:sorted(). + - obj is either a network or address object. +
+ +Custom Exceptions +----------------- + +To support more specific error reporting from class constructors, the +module defines the following exceptions: + +.. exception:: AddressValueError(ValueError) +
+ +.. exception:: NetmaskValueError(ValueError) +
--- a/Misc/NEWS +++ b/Misc/NEWS @@ -124,6 +124,11 @@ Extension Modules