Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9680bdb

Browse files
ncoghlanncoghlan
committed
Issue #14814: Add first draft of PEP 3144 ipaddress module documentation (initial patch by Sandro Tosi)
1 parent d972265 commit 9680bdb

4 files changed

Lines changed: 278 additions & 13 deletions

File tree

‎Doc/howto/ipaddress.rst‎

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
11
.. _ipaddress-howto:
22

3-
***************
4-
Ipaddress Howto
5-
***************
3+
***************************************
4+
An Introduction to the ipaddress module
5+
***************************************
66

77
:author: Peter Moody
8+
:author: Nick Coghlan
89

9-
.. topic:: Abstract
10+
.. topic:: Overview
1011

11-
This document is a gentle introduction to :mod:`ipaddress` module.
12+
This document aims to provide a gentle introduction to :mod:`ipaddress`
13+
module. It is aimed primarily at users that aren't already familiar with
14+
IP networking terminology, but may also be useful to network engineers
15+
wanting an overview of how the ipaddress module represents IP network
16+
addressing concepts.
1217

1318

1419
Creating Address/Network/Interface objects
@@ -40,7 +45,7 @@ IP Host Addresses
4045

4146
Addresses, often referred to as "host addresses" are the most basic unit
4247
when working with IP addressing. The simplest way to create addresses is
43-
to use the ``ip_address`` factory function, which automatically determines
48+
to use the :func:`ipaddress.ip_address` factory function, which automatically determines
4449
whether to create an IPv4 or IPv6 address based on the passed in value::
4550

4651
>>> ipaddress.ip_address('192.0.2.1')
@@ -113,7 +118,7 @@ integer, so the network prefix includes the entire network address::
113118

114119
>>> ipaddress.ip_network(3221225984)
115120
IPv4Network('192.0.2.0/32')
116-
>>> ipaddress.ip_network(42540766411282592856903984951653826560L)
121+
>>> ipaddress.ip_network(42540766411282592856903984951653826560)
117122
IPv6Network('2001:db8::/128')
118123

119124
Creation of a particular kind of network can be forced by calling the
@@ -275,15 +280,18 @@ an integer or string that the other module will accept::
275280
Exceptions raised by :mod:`ipaddress`
276281
=====================================
277282

278-
If you try to create an address/network/interface object with an invalid value
279-
for either the address or netmask, :mod:`ipaddress` will raise an
280-
:exc:`AddressValueError` or :exc:`NetmaskValueError` respectively. However,
281-
this applies only when calling the class constructors directly. The factory
282-
functions and other module level functions will just raise :exc:`ValueError`.
283+
When creating address/network/interface objects using the version-agnostic
284+
factory functions, any errors will be reported as :exc:`ValueError`.
285+
286+
For some use cases, it desirable to know whether it is the address or the
287+
netmask which is incorrect. To support these use cases, the class
288+
constructors actually raise the :exc:`ValueError` subclasses
289+
:exc:`ipaddress.AddressValueError` and :exc:`ipaddress.NetmaskValueError`
290+
to indicate exactly which part of the definition failed to parse correctly.
283291

284292
Both of the module specific exceptions have :exc:`ValueError` as their
285293
parent class, so if you're not concerned with the particular type of error,
286-
you can still do the following::
294+
you can still write code like the following::
287295

288296
try:
289297
ipaddress.IPv4Address(address)

‎Doc/library/internet.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,4 @@ is currently supported on most popular platforms. Here is an overview:
4242
http.cookiejar.rst
4343
xmlrpc.client.rst
4444
xmlrpc.server.rst
45+
ipaddress.rst

‎Doc/library/ipaddress.rst‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
:mod:`ipaddress` --- IPv4/IPv6 manipulation library
2+
===================================================
3+
4+
.. module:: ipaddress
5+
:synopsis: IPv4/IPv6 manipulation library.
6+
.. moduleauthor:: Peter Moody
7+
8+
**Source code:** :source:`Lib/ipaddress.py`
9+
10+
--------------
11+
12+
The :mod:`ipaddress` module provides the capabilities to create, manipulate and
13+
operate on IPv4 and IPv6 addresses and networks.
14+
15+
This is the full module API reference - for an overview and introduction,
16+
see :ref:`ipaddress-howto`.
17+
18+
The functions and classes in this module make it straightforward to handle
19+
various tasks related to IP addresses, including checking whether or not two
20+
hosts are on the same subnet, iterating over all hosts in a particular
21+
subnet, as well as checking whether or not a string represents a valid
22+
IP address or network definition.
23+
24+
25+
Defining IP Addresses and Interfaces
26+
------------------------------------
27+
28+
The :mod:`ipaddress` module provides factory functions to define IP addresses
29+
and networks:
30+
31+
.. function:: ip_address(address)
32+
33+
Return an :class:`IPv4Address` or :class:`IPv6Address` object depending on
34+
the IP address passed as argument. *address* is a string or integer
35+
representing the IP address. Either IPv4 or IPv6 addresses may be supplied;
36+
integers less than 2**32 will be considered to be IPv4 by default. A
37+
:exc:`ValueError` is raised if the *address* passed is neither an IPv4 nor
38+
IPv6 address.
39+
40+
>>> ipaddress.ip_address('192.168.0.1')
41+
IPv4Address('192.168.0.1')
42+
>>> ipaddress.ip_address('2001:db8::')
43+
IPv6Address('2001:db8::')
44+
45+
46+
.. function:: ip_network(address, strict=True)
47+
48+
Return an :class:`IPv4Network` or :class:`IPv6Network` object depending on
49+
the IP address passed as argument. *address* is a string or integer
50+
representing the IP network. Either IPv4 or IPv6 networks may be supplied;
51+
integers less than 2**32 will be considered to be IPv4 by default. *strict*
52+
is passed to :class:`IPv4Network` or :class:`IPv6Network` constructor. A
53+
:exc:`ValueError` is raised if the string passed isn't either an IPv4 or IPv6
54+
address, or if the network has host bits set.
55+
56+
>>> ipaddress.ip_network('192.168.0.0/28')
57+
IPv4Network('192.168.0.0/28')
58+
59+
60+
.. function:: ip_interface(address)
61+
62+
Return an :class:`IPv4Interface` or :class:`IPv6Interface` object depending
63+
on the IP address passed as argument. *address* is a string or integer
64+
representing the IP address. Either IPv4 or IPv6 addresses may be supplied;
65+
integers less than 2**32 will be considered to be IPv4 by default.. A
66+
:exc:`ValueError` is raised if the *address* passed isn't either an IPv4 or
67+
IPv6 address.
68+
69+
70+
Representing IP Addresses and Networks
71+
--------------------------------------
72+
73+
The module defines the following and classes to represent IP addresses
74+
and networks:
75+
76+
.. todo: list the properties and methods
77+
78+
.. class:: IPv4Address(address)
79+
80+
Construct an IPv4 address. *address* is a string or integer representing the
81+
IP address. An :exc:`AddressValueError` is raised if *address* is not a
82+
valid IPv4 address.
83+
84+
>>> ipaddress.IPv4Address('192.168.0.1')
85+
IPv4Address('192.168.0.1')
86+
>>> ipaddress.IPv4Address('192.0.2.1') == ipaddress.IPv4Address(3221225985)
87+
True
88+
89+
90+
.. class:: IPv4Interface(address)
91+
92+
Construct an IPv4 interface. *address* is a string or integer representing
93+
the IP interface. An :exc:`AddressValueError` is raised if *address* is not
94+
a valid IPv4 address.
95+
96+
The network address for the interface is determined by calling
97+
``IPv4Network(address, strict=False)``.
98+
99+
>>> ipaddress.IPv4Interface('192.168.0.0/24')
100+
IPv4Interface('192.168.0.0/24')
101+
>>> ipaddress.IPv4Interface('192.168.0.0/24').network
102+
IPv4Network('192.168.0.0/24')
103+
104+
105+
.. class:: IPv4Network(address, strict=True)
106+
107+
Construct an IPv4 network. *address* is a string or integer representing the
108+
IP address (and optionally the network). An :exc:`AddressValueError` is
109+
raised if *address* is not a valid IPv4 address. A :exc:`NetmaskValueError`
110+
is raised if the netmask is not valid for an IPv4 address.
111+
112+
If *strict* is ``True`` and host bits are set in the supplied address,
113+
then :exc:`ValueError` is raised. Otherwise, the host bits are masked out
114+
to determine the appropriate network address.
115+
116+
>>> ipaddress.IPv4Network('192.0.2.0/27')
117+
IPv4Network('192.0.2.0/27')
118+
>>> ipaddress.IPv4Network('192.0.2.0/27').netmask
119+
IPv4Address('255.255.255.224')
120+
>>> ipaddress.IPv4Network('192.0.2.5/27', strict=False)
121+
IPv4Network('192.0.2.0/27')
122+
123+
124+
.. class:: IPv6Address(address)
125+
126+
Construct an IPv6 address. *address* is a string or integer representing the
127+
IP address. An :exc:`AddressValueError` is raised if *address* is not a
128+
valid IPv6 address.
129+
130+
>>> ipaddress.IPv6Address('2001:db8::1000')
131+
IPv6Address('2001:db8::1000')
132+
133+
134+
.. class:: IPv6Interface(address)
135+
136+
Construct an IPv6 interface. *address* is a string or integer representing
137+
the IP interface. An :exc:`AddressValueError` is raised if *address* is not
138+
a valid IPv6 address.
139+
140+
The network address for the interface is determined by calling
141+
``IPv6Network(address, strict=False)``.
142+
143+
>>> ipaddress.IPv6Interface('2001:db8::1000/96')
144+
IPv6Interface('2001:db8::1000/96')
145+
>>> ipaddress.IPv6Interface('2001:db8::1000/96').network
146+
IPv6Network('2001:db8::/96')
147+
148+
149+
.. class:: IPv6Network(address, strict=True)
150+
151+
Construct an IPv6 network. *address* is a string or integer representing the
152+
IP address (and optionally the network). An :exc:`AddressValueError` is
153+
raised if *address* is not a valid IPv6 address. A :exc:`NetmaskValueError`
154+
is raised if the netmask is not valid for an IPv6 address.
155+
156+
If *strict* is ``True`` and host bits are set in the supplied address,
157+
then :exc:`ValueError` is raised. Otherwise, the host bits are masked out
158+
to determine the appropriate network address.
159+
160+
>>> ipaddress.IPv6Network('2001:db8::/96')
161+
IPv6Network('2001:db8::/96')
162+
>>> ipaddress.IPv6Network('2001:db8::/96').netmask
163+
IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::')
164+
>>> ipaddress.IPv6Network('2001:db8::1000/96', strict=False)
165+
IPv6Network('2001:db8::/96')
166+
167+
168+
Other Module Level Functions
169+
----------------------------
170+
171+
The module also provides the following module level functions:
172+
173+
.. function:: v4_int_to_packed(address)
174+
175+
Represent an address as 4 packed bytes in network (big-endian) order.
176+
*address* is an integer representation of an IPv4 IP address. A
177+
:exc:`ValueError` is raised if the integer is negative or too large to be an
178+
IPv4 IP address.
179+
180+
>>> ipaddress.ip_address(3221225985)
181+
IPv4Address('192.0.2.1')
182+
>>> ipaddress.v4_int_to_packed(3221225985)
183+
b'\xc0\x00\x02\x01'
184+
185+
186+
.. function:: v6_int_to_packed(address)
187+
188+
Represent an address as 16 packed bytes in network (big-endian) order.
189+
*address* is an integer representation of an IPv6 IP address. A
190+
:exc:`ValueError` is raised if the integer is negative or too large to be an
191+
IPv6 IP address.
192+
193+
194+
.. function:: summarize_address_range(first, last)
195+
196+
Return an iterator of the summarized network range given the first and last
197+
IP addresses. *first* is the first :class:`IPv4Address` or
198+
:class:`IPv6Address` in the range and *last* is the last :class:`IPv4Address`
199+
or :class:`IPv6Address` in the range. A :exc:`TypeError` is raised if
200+
*first* or *last* are not IP addresses or are not of the same version. A
201+
:exc:`ValueError` is raised if *last* is not greater than *first* or if
202+
*first* address version is not 4 or 6.
203+
204+
>>> [ipaddr for ipaddr in ipaddress.summarize_address_range(
205+
... ipaddress.IPv4Address('192.0.2.0'),
206+
... ipaddress.IPv4Address('192.0.2.130'))]
207+
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')]
208+
209+
210+
.. function:: collapse_addresses(addresses)
211+
212+
Return an iterator of the collapsed :class:`IPv4Network` or
213+
:class:`IPv6Network` objects. *addresses* is an iterator of
214+
:class:`IPv4Network` or :class:`IPv6Network` objects. A :exc:`TypeError` is
215+
raised if *addresses* contains mixed version objects.
216+
217+
>>> [ipaddr for ipaddr in
218+
... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'),
219+
... ipaddress.IPv4Network('192.0.2.128/25')])]
220+
[IPv4Network('192.0.2.0/24')]
221+
222+
223+
.. function:: get_mixed_type_key(obj)
224+
225+
Return a key suitable for sorting between networks and addresses. Address
226+
and Network objects are not sortable by default; they're fundamentally
227+
different, so the expression::
228+
229+
IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')
230+
231+
doesn't make sense. There are some times however, where you may wish to
232+
have :mod:`ipaddress` sort these anyway. If you need to do this, you can use
233+
this function as the ``key`` argument to :func:`sorted()`.
234+
235+
*obj* is either a network or address object.
236+
237+
238+
Custom Exceptions
239+
-----------------
240+
241+
To support more specific error reporting from class constructors, the
242+
module defines the following exceptions:
243+
244+
.. exception:: AddressValueError(ValueError)
245+
246+
Any value error related to the address.
247+
248+
249+
.. exception:: NetmaskValueError(ValueError)
250+
251+
Any value error related to the netmask.

‎Misc/NEWS‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,11 @@ Extension Modules
124124

125125
- Issue #15000: Support the "unique" x32 architecture in _posixsubprocess.c.
126126

127+
Documentation
128+
-------------
129+
130+
- Issue #14814: Added first draft of ipaddress module API reference
131+
127132
Tests
128133
-----
129134

0 commit comments

Comments
 (0)