Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(3)

Delta Between Two Patch Sets: Doc/library/ipaddress.rst

Issue 18802: ipaddress documentation errors
Left Patch Set: Created 6 years, 6 months ago
Right Patch Set: Created 3 years, 8 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | Lib/test/test_ipaddress.py » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 :mod:`ipaddress` --- IPv4/IPv6 manipulation library 1 :mod:`ipaddress` --- IPv4/IPv6 manipulation library
2 =================================================== 2 ===================================================
3 3
4 .. module:: ipaddress 4 .. module:: ipaddress
5 :synopsis: IPv4/IPv6 manipulation library. 5 :synopsis: IPv4/IPv6 manipulation library.
6 .. moduleauthor:: Peter Moody 6 .. moduleauthor:: Peter Moody
7 7
8 **Source code:** :source:`Lib/ipaddress.py` 8 **Source code:** :source:`Lib/ipaddress.py`
9 9
10 -------------- 10 --------------
11
12 .. note::
13
14 The ``ipaddress`` module has been included in the standard library on a
15 :term:`provisional basis <provisional package>`. Backwards incompatible
16 changes (up to and including removal of the package) may occur if deemed
17 necessary by the core developers.
18 11
19 :mod:`ipaddress` provides the capabilities to create, manipulate and 12 :mod:`ipaddress` provides the capabilities to create, manipulate and
20 operate on IPv4 and IPv6 addresses and networks. 13 operate on IPv4 and IPv6 addresses and networks.
21 14
22 The functions and classes in this module make it straightforward to handle 15 The functions and classes in this module make it straightforward to handle
23 various tasks related to IP addresses, including checking whether or not two 16 various tasks related to IP addresses, including checking whether or not two
24 hosts are on the same subnet, iterating over all hosts in a particular 17 hosts are on the same subnet, iterating over all hosts in a particular
25 subnet, checking whether or not a string represents a valid IP address or 18 subnet, checking whether or not a string represents a valid IP address or
26 network definition, and so on. 19 network definition, and so on.
27 20
28 This is the full module API reference - for an overview and introduction, 21 This is the full module API referencefor an overview and introduction, see
29 see :ref:`ipaddress-howto`. 22 :ref:`ipaddress-howto`.
30 23
31 .. versionadded:: 3.3 24 .. versionadded:: 3.3
32 25
33 26
34 Convenience factory functions 27 Convenience factory functions
35 ----------------------------- 28 -----------------------------
36 29
37 The :mod:`ipaddress` module provides factory functions to conveniently create 30 The :mod:`ipaddress` module provides factory functions to conveniently create
38 IP addresses, networks and interfaces: 31 IP addresses, networks and interfaces:
39 32
(...skipping 51 matching lines...) Expand 10 before | Expand all | Expand 10 after
91 84
92 IP Addresses 85 IP Addresses
93 ------------ 86 ------------
94 87
95 Address objects 88 Address objects
96 ^^^^^^^^^^^^^^^ 89 ^^^^^^^^^^^^^^^
97 90
98 The :class:`IPv4Address` and :class:`IPv6Address` objects share a lot of common 91 The :class:`IPv4Address` and :class:`IPv6Address` objects share a lot of common
99 attributes. Some attributes that are only meaningful for IPv6 addresses are 92 attributes. Some attributes that are only meaningful for IPv6 addresses are
100 also implemented by :class:`IPv4Address` objects, in order to make it easier to 93 also implemented by :class:`IPv4Address` objects, in order to make it easier to
101 write code that handles both IP versions correctly. 94 write code that handles both IP versions correctly. Address objects are
95 hashable, so they can be used as keys in dictionaries.
102 96
103 .. class:: IPv4Address(address) 97 .. class:: IPv4Address(address)
104 98
105 Construct an IPv4 address. An :exc:`AddressValueError` is raised if 99 Construct an IPv4 address. An :exc:`AddressValueError` is raised if
106 *address* is not a valid IPv4 address. 100 *address* is not a valid IPv4 address.
107 101
108 The following constitutes a valid IPv4 address: 102 The following constitutes a valid IPv4 address:
109 103
110 1. A string in decimal-dot notation, consisting of four decimal integers in 104 1. A string in decimal-dot notation, consisting of four decimal integers in
111 the inclusive range 0-255, separated by dots (e.g. ``192.168.0.1``). Each 105 the inclusive range 0-255, separated by dots (e.g. ``192.168.0.1``). Each
112 integer represents an octet (byte) in the address. Leading zeroes are 106 integer represents an octet (byte) in the address. Leading zeroes are
113 tolerated only for values less then 8 (as there is no ambiguity 107 tolerated only for values less than 8 (as there is no ambiguity
114 between the decimal and octal interpretations of such strings). 108 between the decimal and octal interpretations of such strings).
115 2. An integer that fits into 32 bits. 109 2. An integer that fits into 32 bits.
116 3. An integer packed into a :class:`bytes` object of length 4 (most 110 3. An integer packed into a :class:`bytes` object of length 4 (most
117 significant octet first). 111 significant octet first).
118 112
119 >>> ipaddress.IPv4Address('192.168.0.1') 113 >>> ipaddress.IPv4Address('192.168.0.1')
120 IPv4Address('192.168.0.1') 114 IPv4Address('192.168.0.1')
121 >>> ipaddress.IPv4Address(3232235521) 115 >>> ipaddress.IPv4Address(3232235521)
122 IPv4Address('192.168.0.1') 116 IPv4Address('192.168.0.1')
123 >>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01') 117 >>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01')
(...skipping 22 matching lines...) Expand all
146 set to zero, these two attributes are always the same as ``str(addr)`` 140 set to zero, these two attributes are always the same as ``str(addr)``
147 for IPv4 addresses. Exposing these attributes makes it easier to 141 for IPv4 addresses. Exposing these attributes makes it easier to
148 write display code that can handle both IPv4 and IPv6 addresses. 142 write display code that can handle both IPv4 and IPv6 addresses.
149 143
150 .. attribute:: packed 144 .. attribute:: packed
151 145
152 The binary representation of this address - a :class:`bytes` object of 146 The binary representation of this address - a :class:`bytes` object of
153 the appropriate length (most significant octet first). This is 4 bytes 147 the appropriate length (most significant octet first). This is 4 bytes
154 for IPv4 and 16 bytes for IPv6. 148 for IPv4 and 16 bytes for IPv6.
155 149
150 .. attribute:: reverse_pointer
151
152 The name of the reverse DNS PTR record for the IP address, e.g.::
153
154 >>> ipaddress.ip_address("127.0.0.1").reverse_pointer
155 '1.0.0.127.in-addr.arpa'
156 >>> ipaddress.ip_address("2001:db8::1").reverse_pointer
157 '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.a rpa'
158
159 This is the name that could be used for performing a PTR lookup, not the
160 resolved hostname itself.
161
162 .. versionadded:: 3.5
163
156 .. attribute:: is_multicast 164 .. attribute:: is_multicast
157 165
158 ``True`` if the address is reserved for multicast use. See 166 ``True`` if the address is reserved for multicast use. See
159 :RFC:`3171` (for IPv4) or :RFC:`2373` (for IPv6). 167 :RFC:`3171` (for IPv4) or :RFC:`2373` (for IPv6).
160 168
161 .. attribute:: is_private 169 .. attribute:: is_private
162 170
163 ``True`` if the address is allocated for private networks. See 171 ``True`` if the address is allocated for private networks. See
164 :RFC:`1918` (for IPv4) or :RFC:`4193` (for IPv6). 172 iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
173 (for IPv6).
174
175 .. attribute:: is_global
176
177 ``True`` if the address is allocated for public networks. See
178 iana-ipv4-special-registry_ (for IPv4) or iana-ipv6-special-registry_
179 (for IPv6).
180
181 .. versionadded:: 3.4
165 182
166 .. attribute:: is_unspecified 183 .. attribute:: is_unspecified
167 184
168 ``True`` if the address is unspecified. See :RFC:`5375` (for IPv4) 185 ``True`` if the address is unspecified. See :RFC:`5735` (for IPv4)
169 or :RFC:`2373` (for IPv6). 186 or :RFC:`2373` (for IPv6).
170 187
171 .. attribute:: is_reserved 188 .. attribute:: is_reserved
172 189
173 ``True`` if the address is otherwise IETF reserved. 190 ``True`` if the address is otherwise IETF reserved.
174 191
175 .. attribute:: is_loopback 192 .. attribute:: is_loopback
176 193
177 ``True`` if this is a loopback address. See :RFC:`3330` (for IPv4) 194 ``True`` if this is a loopback address. See :RFC:`3330` (for IPv4)
178 or :RFC:`2373` (for IPv6). 195 or :RFC:`2373` (for IPv6).
179 196
180 .. attribute:: is_link_local 197 .. attribute:: is_link_local
181 198
182 ``True`` if the address is reserved for link-local usage. See 199 ``True`` if the address is reserved for link-local usage. See
183 :RFC:`3927`. 200 :RFC:`3927`.
201
202 .. _iana-ipv4-special-registry: https://www.iana.org/assignments/iana-ipv4-speci al-registry/iana-ipv4-special-registry.xhtml
203 .. _iana-ipv6-special-registry: https://www.iana.org/assignments/iana-ipv6-speci al-registry/iana-ipv6-special-registry.xhtml
184 204
185 205
186 .. class:: IPv6Address(address) 206 .. class:: IPv6Address(address)
187 207
188 Construct an IPv6 address. An :exc:`AddressValueError` is raised if 208 Construct an IPv6 address. An :exc:`AddressValueError` is raised if
189 *address* is not a valid IPv6 address. 209 *address* is not a valid IPv6 address.
190 210
191 The following constitutes a valid IPv6 address: 211 The following constitutes a valid IPv6 address:
192 212
193 1. A string consisting of eight groups of four hexadecimal digits, each 213 1. A string consisting of eight groups of four hexadecimal digits, each
(...skipping 15 matching lines...) Expand all
209 groups omitted and the longest sequence of groups consisting entirely of 229 groups omitted and the longest sequence of groups consisting entirely of
210 zeroes collapsed to a single empty group. 230 zeroes collapsed to a single empty group.
211 231
212 This is also the value returned by ``str(addr)`` for IPv6 addresses. 232 This is also the value returned by ``str(addr)`` for IPv6 addresses.
213 233
214 .. attribute:: exploded 234 .. attribute:: exploded
215 235
216 The long form of the address representation, with all leading zeroes and 236 The long form of the address representation, with all leading zeroes and
217 groups consisting entirely of zeroes included. 237 groups consisting entirely of zeroes included.
218 238
239
240 For the following attributes, see the corresponding documentation of the
241 :class:`IPv4Address` class:
242
219 .. attribute:: packed 243 .. attribute:: packed
244 .. attribute:: reverse_pointer
220 .. attribute:: version 245 .. attribute:: version
221 .. attribute:: max_prefixlen 246 .. attribute:: max_prefixlen
222 .. attribute:: is_multicast 247 .. attribute:: is_multicast
223 .. attribute:: is_private 248 .. attribute:: is_private
249 .. attribute:: is_global
224 .. attribute:: is_unspecified 250 .. attribute:: is_unspecified
225 .. attribute:: is_reserved 251 .. attribute:: is_reserved
226 .. attribute:: is_loopback 252 .. attribute:: is_loopback
227 .. attribute:: is_link_local 253 .. attribute:: is_link_local
228 254
229 Refer to the corresponding attribute documentation in 255 .. versionadded:: 3.4
230 :class:`IPv4Address` 256 is_global
231 257
232 .. attribute:: is_site_local 258 .. attribute:: is_site_local
233 259
234 ``True`` if the address is reserved for site-local usage. Note that 260 ``True`` if the address is reserved for site-local usage. Note that
235 the site-local address space has been deprecated by :RFC:`3879`. Use 261 the site-local address space has been deprecated by :RFC:`3879`. Use
236 :attr:`~IPv4Address.is_private` to test if this address is in the 262 :attr:`~IPv4Address.is_private` to test if this address is in the
237 space of unique local addresses as defined by :RFC:`4193`. 263 space of unique local addresses as defined by :RFC:`4193`.
238 264
239 .. attribute:: ipv4_mapped 265 .. attribute:: ipv4_mapped
240 266
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after
275 301
276 302
277 Operators 303 Operators
278 ^^^^^^^^^ 304 ^^^^^^^^^
279 305
280 Address objects support some operators. Unless stated otherwise, operators can 306 Address objects support some operators. Unless stated otherwise, operators can
281 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 307 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
282 IPv6). 308 IPv6).
283 309
284 310
285 Logical operators 311 Comparison operators
286 """"""""""""""""" 312 """"""""""""""""""""
287 313
288 Address objects can be compared with the usual set of logical operators. Some 314 Address objects can be compared with the usual set of comparison operators. Som e
289 examples:: 315 examples::
290 316
291 >>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1') 317 >>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1')
292 True 318 True
293 >>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1') 319 >>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1')
294 False 320 False
295 >>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1') 321 >>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1')
296 True 322 True
297
298
299 Hashing
300 """""""
301
302 Address objects are hashable, so they can be used as keys in dictionaries.
303 323
304 324
305 Arithmetic operators 325 Arithmetic operators
306 """""""""""""""""""" 326 """"""""""""""""""""
307 327
308 Integers can be added to or subtracted from address objects. Some examples:: 328 Integers can be added to or subtracted from address objects. Some examples::
309 329
310 >>> IPv4Address('127.0.0.2') + 3 330 >>> IPv4Address('127.0.0.2') + 3
311 IPv4Address('127.0.0.5') 331 IPv4Address('127.0.0.5')
312 >>> IPv4Address('127.0.0.2') - 3 332 >>> IPv4Address('127.0.0.2') - 3
(...skipping 29 matching lines...) Expand all
342 host mask equivalent to ``/24`` in IPv4 is ``0.0.0.255``. 362 host mask equivalent to ``/24`` in IPv4 is ``0.0.0.255``.
343 363
344 364
345 Network objects 365 Network objects
346 ^^^^^^^^^^^^^^^ 366 ^^^^^^^^^^^^^^^
347 367
348 All attributes implemented by address objects are implemented by network 368 All attributes implemented by address objects are implemented by network
349 objects as well. In addition, network objects implement additional attributes. 369 objects as well. In addition, network objects implement additional attributes.
350 All of these are common between :class:`IPv4Network` and :class:`IPv6Network`, 370 All of these are common between :class:`IPv4Network` and :class:`IPv6Network`,
351 so to avoid duplication they are only documented for :class:`IPv4Network`. 371 so to avoid duplication they are only documented for :class:`IPv4Network`.
372 Network objects are hashable, so they can be used as keys in dictionaries.
352 373
353 .. class:: IPv4Network(address, strict=True) 374 .. class:: IPv4Network(address, strict=True)
354 375
355 Construct an IPv4 network definition. *address* can be one of the following: 376 Construct an IPv4 network definition. *address* can be one of the following:
356 377
357 1. A string consisting of an IP address and an optional mask, separated by 378 1. A string consisting of an IP address and an optional mask, separated by
358 a slash (``/``). The IP address is the network address, and the mask 379 a slash (``/``). The IP address is the network address, and the mask
359 can be either a single number, which means it's a *prefix*, or a string 380 can be either a single number, which means it's a *prefix*, or a string
360 representation of an IPv4 address. If it's the latter, the mask is 381 representation of an IPv4 address. If it's the latter, the mask is
361 interpreted as a *net mask* if possible, or as a *host mask* otherwise. 382 interpreted as a *net mask* if possible, or as a *host mask* otherwise.
362 If no mask is provided, it's considered to be ``/32``. 383 If no mask is provided, it's considered to be ``/32``.
363 384
364 For example, the following *address* specifications are equivalent: 385 For example, the following *address* specifications are equivalent:
365 ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and 386 ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and
366 ``192.168.1.0/0.0.0.255``. 387 ``192.168.1.0/0.0.0.255``.
367 388
368 Note that the two ambiguous cases are both treated as netmasks: 389 Note that the two ambiguous cases are both treated as net masks:
369 ``0.0.0.0/0.0.0.0`` is ``0.0.0.0/0``, and 390 ``0.0.0.0/0.0.0.0`` is ``0.0.0.0/0``, and
370 ``1.2.3.4/255.255.255.255`` is ``1.2.3.4/32``. 391 ``1.2.3.4/255.255.255.255`` is ``1.2.3.4/32``.
371 392
372 2. An integer that fits into 32 bits. This is equivalent to a 393 2. An integer that fits into 32 bits. This is equivalent to a
373 single-address network, with the network address being *address* and 394 single-address network, with the network address being *address* and
374 the mask being ``/32``. 395 the mask being ``/32``.
375 396
376 3. An integer packed into a :class:`bytes` object of length 4, big-endian. 397 3. An integer packed into a :class:`bytes` object of length 4, big-endian.
377 The interpretation is similar to an integer *address*. 398 The interpretation is similar to an integer *address*.
378 399
400 4. A two-tuple of an address description and a netmask, where the address
401 description is either a string, a 32-bits integer, a 4-bytes packed
402 integer, or an existing IPv4Address object; and the netmask is either
403 an integer representing the prefix length (e.g. ``24``) or a string
404 representing the prefix mask (e.g. ``255.255.255.0``).
405
379 An :exc:`AddressValueError` is raised if *address* is not a valid IPv4 406 An :exc:`AddressValueError` is raised if *address* is not a valid IPv4
380 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for 407 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for
381 an IPv4 address. 408 an IPv4 address.
382 409
383 If *strict* is ``True`` and host bits are set in the supplied address, 410 If *strict* is ``True`` and host bits are set in the supplied address,
384 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out 411 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out
385 to determine the appropriate network address. 412 to determine the appropriate network address.
386 413
387 Unless stated otherwise, all network methods accepting other network/address 414 Unless stated otherwise, all network methods accepting other network/address
388 objects will raise :exc:`TypeError` if the argument's IP version is 415 objects will raise :exc:`TypeError` if the argument's IP version is
389 incompatible to ``self`` 416 incompatible to ``self``.
417
418 .. versionchanged:: 3.5
419
420 Added the two-tuple form for the *address* constructor parameter.
390 421
391 .. attribute:: version 422 .. attribute:: version
392 .. attribute:: max_prefixlen 423 .. attribute:: max_prefixlen
393 424
394 Refer to the corresponding attribute documentation in 425 Refer to the corresponding attribute documentation in
395 :class:`IPv4Address` 426 :class:`IPv4Address`.
396 427
397 .. attribute:: is_multicast 428 .. attribute:: is_multicast
398 .. attribute:: is_private 429 .. attribute:: is_private
399 .. attribute:: is_unspecified 430 .. attribute:: is_unspecified
400 .. attribute:: is_reserved 431 .. attribute:: is_reserved
401 .. attribute:: is_loopback 432 .. attribute:: is_loopback
402 .. attribute:: is_link_local 433 .. attribute:: is_link_local
403 434
404 These attributes are true for the network as a whole if they are true 435 These attributes are true for the network as a whole if they are true
405 for both the network address and the broadcast address 436 for both the network address and the broadcast address.
406 437
407 .. attribute:: network_address 438 .. attribute:: network_address
408 439
409 The network address for the network. The network address and the 440 The network address for the network. The network address and the
410 prefix length together uniquely define a network. 441 prefix length together uniquely define a network.
411 442
412 .. attribute:: broadcast_address 443 .. attribute:: broadcast_address
413 444
414 The broadcast address for the network. Packets sent to the broadcast 445 The broadcast address for the network. Packets sent to the broadcast
415 address should be received by every host on the network. 446 address should be received by every host on the network.
416 447
448 .. attribute:: hostmask
449
450 The host mask, as an :class:`IPv4Address` object.
451
417 .. attribute:: netmask 452 .. attribute:: netmask
418 453
419 The netmask, as an :class:`IPv4Address` object. 454 The net mask, as an :class:`IPv4Address` object.
420
421 .. attribute:: hostmask
422
423 The host mask, as an :class:`IPv4Address` object.
424 455
425 .. attribute:: with_prefixlen 456 .. attribute:: with_prefixlen
426 .. attribute:: compressed 457 .. attribute:: compressed
427 .. attribute:: exploded 458 .. attribute:: exploded
428 459
429 A string representation of the network, with the mask in prefix 460 A string representation of the network, with the mask in prefix
430 notation. 461 notation.
431 462
432 ``with_prefixlen`` and ``compressed`` are always the same as 463 ``with_prefixlen`` and ``compressed`` are always the same as
433 ``str(network)``. 464 ``str(network)``.
(...skipping 104 matching lines...) Expand 10 before | Expand all | Expand 10 after
538 .. class:: IPv6Network(address, strict=True) 569 .. class:: IPv6Network(address, strict=True)
539 570
540 Construct an IPv6 network definition. *address* can be one of the following: 571 Construct an IPv6 network definition. *address* can be one of the following:
541 572
542 1. A string consisting of an IP address and an optional prefix length, 573 1. A string consisting of an IP address and an optional prefix length,
543 separated by a slash (``/``). The IP address is the network address, 574 separated by a slash (``/``). The IP address is the network address,
544 and the prefix length must be a single number, the *prefix*. If no 575 and the prefix length must be a single number, the *prefix*. If no
545 prefix length is provided, it's considered to be ``/128``. 576 prefix length is provided, it's considered to be ``/128``.
546 577
547 For example, the *address* specification might be ``2001:db00::0/24``. 578 For example, the *address* specification might be ``2001:db00::0/24``.
548 579
549 Note that IPv6 networks can't be specified using a net mask or a host 580 Note that IPv6 networks can't be specified using a net mask or a host
550 mask - those features are only in :class:`IPv4Network`. 581 mask - those features are only in :class:`IPv4Network`.
551 582
552 2. An integer that fits into 128 bits. This is equivalent to a 583 2. An integer that fits into 128 bits. This is equivalent to a
553 single-address network, with the network address being *address* and 584 single-address network, with the network address being *address* and
554 the mask being ``/128``. 585 the mask being ``/128``.
555 586
556 3. An integer packed into a :class:`bytes` object of length 16, bit-endian. 587 3. An integer packed into a :class:`bytes` object of length 16, big-endian.
557 The interpretation is similar to an integer *address*. 588 The interpretation is similar to an integer *address*.
589
590 4. A two-tuple of an address description and a netmask, where the address
591 description is either a string, a 128-bits integer, a 16-bytes packed
592 integer, or an existing IPv4Address object; and the netmask is an
593 integer representing the prefix length.
558 594
559 An :exc:`AddressValueError` is raised if *address* is not a valid IPv6 595 An :exc:`AddressValueError` is raised if *address* is not a valid IPv6
560 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for 596 address. A :exc:`NetmaskValueError` is raised if the mask is not valid for
561 an IPv6 address. 597 an IPv6 address.
562 598
563 If *strict* is ``True`` and host bits are set in the supplied address, 599 If *strict* is ``True`` and host bits are set in the supplied address,
564 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out 600 then :exc:`ValueError` is raised. Otherwise, the host bits are masked out
565 to determine the appropriate network address. 601 to determine the appropriate network address.
602
603 .. versionchanged:: 3.5
604
605 Added the two-tuple form for the *address* constructor parameter.
566 606
567 .. attribute:: version 607 .. attribute:: version
568 .. attribute:: max_prefixlen 608 .. attribute:: max_prefixlen
569 .. attribute:: is_multicast 609 .. attribute:: is_multicast
570 .. attribute:: is_private 610 .. attribute:: is_private
571 .. attribute:: is_unspecified 611 .. attribute:: is_unspecified
572 .. attribute:: is_reserved 612 .. attribute:: is_reserved
573 .. attribute:: is_loopback 613 .. attribute:: is_loopback
574 .. attribute:: is_link_local 614 .. attribute:: is_link_local
575 .. attribute:: network_address 615 .. attribute:: network_address
576 .. attribute:: broadcast_address 616 .. attribute:: broadcast_address
617 .. attribute:: hostmask
577 .. attribute:: netmask 618 .. attribute:: netmask
578 .. attribute:: hostmask
579 .. attribute:: with_prefixlen 619 .. attribute:: with_prefixlen
580 .. attribute:: compressed 620 .. attribute:: compressed
581 .. attribute:: exploded 621 .. attribute:: exploded
582 .. attribute:: with_netmask 622 .. attribute:: with_netmask
583 .. attribute:: with_hostmask 623 .. attribute:: with_hostmask
584 .. attribute:: num_addresses 624 .. attribute:: num_addresses
585 .. attribute:: prefixlen 625 .. attribute:: prefixlen
586 .. method:: hosts() 626 .. method:: hosts()
587 .. method:: overlaps(other) 627 .. method:: overlaps(other)
588 .. method:: address_exclude(network) 628 .. method:: address_exclude(network)
589 .. method:: subnets(prefixlen_diff=1, new_prefix=None) 629 .. method:: subnets(prefixlen_diff=1, new_prefix=None)
590 .. method:: supernet(prefixlen_diff=1, new_prefix=None) 630 .. method:: supernet(prefixlen_diff=1, new_prefix=None)
591 .. method:: compare_networks(other) 631 .. method:: compare_networks(other)
592 632
593 Refer to the corresponding attribute documentation in 633 Refer to the corresponding attribute documentation in
594 :class:`IPv4Network` 634 :class:`IPv4Network`.
595 635
596 .. attribute:: is_site_local 636 .. attribute:: is_site_local
597 637
598 These attribute is true for the network as a whole if it is true 638 These attribute is true for the network as a whole if it is true
599 for both the network address and the broadcast address 639 for both the network address and the broadcast address.
600 640
601 641
602 Operators 642 Operators
603 ^^^^^^^^^ 643 ^^^^^^^^^
604 644
605 Network objects support some operators. Unless stated otherwise, operators can 645 Network objects support some operators. Unless stated otherwise, operators can
606 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 646 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
607 IPv6). 647 IPv6).
608 648
609 649
610 Logical operators 650 Logical operators
611 """"""""""""""""" 651 """""""""""""""""
612 652
613 Network objects can be compared with the usual set of logical operators. 653 Network objects can be compared with the usual set of logical operators.
614 Network objects are ordered first by network address, then by net mask. 654 Network objects are ordered first by network address, then by net mask.
615
616
617 Hashing
618 """""""
619
620 Network objects are hashable, so they can be used as keys in dictionaries.
621 655
622 656
623 Iteration 657 Iteration
624 """"""""" 658 """""""""
625 659
626 Network objects can be iterated to list all the addresses belonging to the 660 Network objects can be iterated to list all the addresses belonging to the
627 network. For iteration, *all* hosts are returned, including unusable hosts 661 network. For iteration, *all* hosts are returned, including unusable hosts
628 (for usable hosts, use the :meth:`~IPv4Network.hosts` method). An 662 (for usable hosts, use the :meth:`~IPv4Network.hosts` method). An
629 example:: 663 example::
630 664
631 >>> for addr in IPv4Network('192.0.2.0/28'): 665 >>> for addr in IPv4Network('192.0.2.0/28'):
632 ... addr 666 ... addr
633 ... 667 ...
634 IPv4Address('192.0.2.0') 668 IPv4Address('192.0.2.0')
635 IPv4Address('192.0.2.1') 669 IPv4Address('192.0.2.1')
636 IPv4Address('192.0.2.2') 670 IPv4Address('192.0.2.2')
637 IPv4Address('192.0.2.3') 671 IPv4Address('192.0.2.3')
638 IPv4Address('192.0.2.4') 672 IPv4Address('192.0.2.4')
639 IPv4Address('192.0.2.5') 673 IPv4Address('192.0.2.5')
640 IPv4Address('192.0.2.6') 674 IPv4Address('192.0.2.6')
641 IPv4Address('192.0.2.7') 675 IPv4Address('192.0.2.7')
642 IPv4Address('192.0.2.8') 676 IPv4Address('192.0.2.8')
(...skipping 17 matching lines...) Expand all
660 IPv4Address('192.0.2.15') 694 IPv4Address('192.0.2.15')
661 >>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28') 695 >>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28')
662 True 696 True
663 >>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28') 697 >>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28')
664 False 698 False
665 699
666 700
667 Interface objects 701 Interface objects
668 ----------------- 702 -----------------
669 703
704 Interface objects are hashable, so they can be used as keys in dictionaries.
705
670 .. class:: IPv4Interface(address) 706 .. class:: IPv4Interface(address)
671 707
672 Construct an IPv4 interface. The meaning of *address* is as in the 708 Construct an IPv4 interface. The meaning of *address* is as in the
673 constructor of :class:`IPv4Network`, except that arbitrary host addresses 709 constructor of :class:`IPv4Network`, except that arbitrary host addresses
674 are always accepted. 710 are always accepted.
675 711
676 :class:`IPv4Interface` is a subclass of :class:`IPv4Address`, so it inherits 712 :class:`IPv4Interface` is a subclass of :class:`IPv4Address`, so it inherits
677 all the attributes from that class. In addition, the following attributes 713 all the attributes from that class. In addition, the following attributes
678 are available: 714 are available:
679 715
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after
734 .. attribute:: with_netmask 770 .. attribute:: with_netmask
735 .. attribute:: with_hostmask 771 .. attribute:: with_hostmask
736 772
737 Refer to the corresponding attribute documentation in 773 Refer to the corresponding attribute documentation in
738 :class:`IPv4Interface`. 774 :class:`IPv4Interface`.
739 775
740 776
741 Operators 777 Operators
742 ^^^^^^^^^ 778 ^^^^^^^^^
743 779
744 Interface objects support some operators. Unless stated otherwise, operators ca n 780 Interface objects support some operators. Unless stated otherwise, operators
745 only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with 781 can only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
746 IPv6). 782 IPv6).
747 783
748 784
749 Logical operators 785 Logical operators
750 """"""""""""""""" 786 """""""""""""""""
751 787
752 Interface objects can be compared with the usual set of logical operators. 788 Interface objects can be compared with the usual set of logical operators.
753 789
754 For equality comparison (``==`` and ``!=``), both the IP address and network mus t 790 For equality comparison (``==`` and ``!=``), both the IP address and network
755 be the same for the objects to be equal. An Interface will not compare equal to 791 must be the same for the objects to be equal. An interface will not compare
756 any Address or Network object. 792 equal to any address or network object.
757 793
758 For ordering (``<``, ``>``, etc) the rules are different. 794 For ordering (``<``, ``>``, etc) the rules are different. Interface and
759 Interface and address objects with the same IP version can be compared, and the 795 address objects with the same IP version can be compared, and the address
760 address objects will always sort before the interface objects. Two interface 796 objects will always sort before the interface objects. Two interface objects
ezio.melotti 2013/08/23 22:21:22 There's an extra space here. Also a couple of line
761 objects are compared by comparing their networks, using the same rules as 797 are compared by comparing their networks, using the same rules as
762 :class:`IPv4Network` or :class:`IPv6Network`. The IP address plays no part in 798 :class:`IPv4Network` or :class:`IPv6Network`. The IP address plays no part in
763 the comparison. Note that you will get strange results when comparing two 799 the comparison. Note that you will get strange results when comparing two
ezio.melotti 2013/08/23 22:21:22 "getting strange results" doesn't sound appropriat
764 interface objects with the same network but different IP addresses. E.g.:: 800 interface objects with the same network but different IP addresses::
765 801
766 >>> import ipaddress 802 >>> a = ipaddress.IPv4Interface('128.0.0.3/8')
767 >>> a = ipaddress.IPv4Interface('128.0.0.3/8') 803 >>> b = ipaddress.IPv4Interface('128.0.0.5/8')
768 >>> b = ipaddress.IPv4Interface('128.0.0.5/8') 804 >>> a < b
769 >>> a < b 805 False
770 False 806 >>> b < a
771 >>> b < a 807 False
772 False 808 >>> a > b
773 >>> a > b 809 True
774 True 810 >>> b > a
775 >>> b > a 811 True
776 True
777
778 Also, note that since the comparison rules for interfaces are different from the
779 rules for addresses, this means that :class:`IPv4Interface` and its base class
780 :class:`IPv4Address` don't follow the Liskov Substitution Principle. I.e. you
ezio.melotti 2013/08/23 22:21:22 I'm not sure it's necessary to mention the LSP. A
781 can't pass a :class:`IPv4Interface` to code that expects a :class:`IPv4Address`
782 and uses comparison operators or hashing. Similarly for :class:`IPv6Interface`
783 and :class:`IPv6Address`.
784
785
786 Hashing
787 """""""
788
789 Interface objects are hashable, so they can be used as keys in dictionaries.
790 812
791 813
792 Other Module Level Functions 814 Other Module Level Functions
793 ---------------------------- 815 ----------------------------
794 816
795 The module also provides the following module level functions: 817 The module also provides the following module level functions:
796 818
797 .. function:: v4_int_to_packed(address) 819 .. function:: v4_int_to_packed(address)
798 820
799 Represent an address as 4 packed bytes in network (big-endian) order. 821 Represent an address as 4 packed bytes in network (big-endian) order.
(...skipping 47 matching lines...) Expand 10 before | Expand all | Expand 10 after
847 .. function:: get_mixed_type_key(obj) 869 .. function:: get_mixed_type_key(obj)
848 870
849 Return a key suitable for sorting between networks and addresses. Address 871 Return a key suitable for sorting between networks and addresses. Address
850 and Network objects are not sortable by default; they're fundamentally 872 and Network objects are not sortable by default; they're fundamentally
851 different, so the expression:: 873 different, so the expression::
852 874
853 IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24') 875 IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')
854 876
855 doesn't make sense. There are some times however, where you may wish to 877 doesn't make sense. There are some times however, where you may wish to
856 have :mod:`ipaddress` sort these anyway. If you need to do this, you can use 878 have :mod:`ipaddress` sort these anyway. If you need to do this, you can use
857 this function as the ``key`` argument to :func:`sorted()`. 879 this function as the *key* argument to :func:`sorted()`.
858 880
859 *obj* is either a network or address object. 881 *obj* is either a network or address object.
860 882
861 883
862 Custom Exceptions 884 Custom Exceptions
863 ----------------- 885 -----------------
864 886
865 To support more specific error reporting from class constructors, the 887 To support more specific error reporting from class constructors, the
866 module defines the following exceptions: 888 module defines the following exceptions:
867 889
868 .. exception:: AddressValueError(ValueError) 890 .. exception:: AddressValueError(ValueError)
869 891
870 Any value error related to the address. 892 Any value error related to the address.
871 893
872 894
873 .. exception:: NetmaskValueError(ValueError) 895 .. exception:: NetmaskValueError(ValueError)
874 896
875 Any value error related to the netmask. 897 Any value error related to the net mask.
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+