Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 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 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 12 | .. note:: |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 13 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 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 | |
| 19 | :mod:`ipaddress` provides the capabilities to create, manipulate and |
| 20 | operate on IPv4 and IPv6 addresses and networks. |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 21 | |
| 22 | 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 |
| 24 | hosts are on the same subnet, iterating over all hosts in a particular |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 25 | subnet, checking whether or not a string represents a valid IP address or |
| 26 | network definition, and so on. |
| 27 | |
| 28 | This is the full module API reference - for an overview and introduction, |
| 29 | see :ref:`ipaddress-howto`. |
| 30 | |
| 31 | .. versionadded:: 3.3 |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 32 | |
| 33 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 34 | Convenience factory functions |
| 35 | ----------------------------- |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 36 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 37 | The :mod:`ipaddress` module provides factory functions to conveniently create |
| 38 | IP addresses, networks and interfaces: |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 39 | |
| 40 | .. function:: ip_address(address) |
| 41 | |
| 42 | Return an :class:`IPv4Address` or :class:`IPv6Address` object depending on |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 43 | the IP address passed as argument. Either IPv4 or IPv6 addresses may be |
| 44 | supplied; integers less than 2**32 will be considered to be IPv4 by default. |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 45 | A :exc:`ValueError` is raised if *address* does not represent a valid IPv4 |
| 46 | or IPv6 address. |
| 47 | |
| 48 | .. testsetup:: |
| 49 | >>> import ipaddress |
| 50 | >>> from ipaddress import (ip_network, IPv4Address, IPv4Interface, |
| 51 | ... IPv4Network) |
| 52 | |
| 53 | :: |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 54 | |
| 55 | >>> ipaddress.ip_address('192.168.0.1') |
| 56 | IPv4Address('192.168.0.1') |
| 57 | >>> ipaddress.ip_address('2001:db8::') |
| 58 | IPv6Address('2001:db8::') |
| 59 | |
| 60 | |
| 61 | .. function:: ip_network(address, strict=True) |
| 62 | |
| 63 | Return an :class:`IPv4Network` or :class:`IPv6Network` object depending on |
| 64 | the IP address passed as argument. *address* is a string or integer |
| 65 | representing the IP network. Either IPv4 or IPv6 networks may be supplied; |
| 66 | integers less than 2**32 will be considered to be IPv4 by default. *strict* |
| 67 | is passed to :class:`IPv4Network` or :class:`IPv6Network` constructor. A |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 68 | :exc:`ValueError` is raised if *address* does not represent a valid IPv4 or |
| 69 | IPv6 address, or if the network has host bits set. |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 70 | |
| 71 | >>> ipaddress.ip_network('192.168.0.0/28') |
| 72 | IPv4Network('192.168.0.0/28') |
| 73 | |
| 74 | |
| 75 | .. function:: ip_interface(address) |
| 76 | |
| 77 | Return an :class:`IPv4Interface` or :class:`IPv6Interface` object depending |
| 78 | on the IP address passed as argument. *address* is a string or integer |
| 79 | representing the IP address. Either IPv4 or IPv6 addresses may be supplied; |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 80 | integers less than 2**32 will be considered to be IPv4 by default. A |
| 81 | :exc:`ValueError` is raised if *address* does not represent a valid IPv4 or |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 82 | IPv6 address. |
| 83 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 84 | One downside of these convenience functions is that the need to handle both |
| 85 | IPv4 and IPv6 formats means that error messages provide minimal |
| 86 | information on the precise error, as the functions don't know whether the |
| 87 | IPv4 or IPv6 format was intended. More detailed error reporting can be |
| 88 | obtained by calling the appropriate version specific class constructors |
| 89 | directly. |
| 90 | |
| 91 | |
| 92 | IP Addresses |
| 93 | ------------ |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 94 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 95 | Address objects |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 96 | ^^^^^^^^^^^^^^^ |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 97 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 98 | The :class:`IPv4Address` and :class:`IPv6Address` objects share a lot of common |
| 99 | 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 |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 101 | write code that handles both IP versions correctly. |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 102 | |
| 103 | .. class:: IPv4Address(address) |
| 104 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 105 | Construct an IPv4 address. An :exc:`AddressValueError` is raised if |
| 106 | *address* is not a valid IPv4 address. |
| 107 | |
| 108 | The following constitutes a valid IPv4 address: |
| 109 | |
| 110 | 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 |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 112 | integer represents an octet (byte) in the address. Leading zeroes are |
| 113 | tolerated only for values less then 8 (as there is no ambiguity |
| 114 | between the decimal and octal interpretations of such strings). |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 115 | 2. An integer that fits into 32 bits. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 116 | 3. An integer packed into a :class:`bytes` object of length 4 (most |
| 117 | significant octet first). |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 118 | |
| 119 | >>> ipaddress.IPv4Address('192.168.0.1') |
| 120 | IPv4Address('192.168.0.1') |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 121 | >>> ipaddress.IPv4Address(3232235521) |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 122 | IPv4Address('192.168.0.1') |
| 123 | >>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01') |
| 124 | IPv4Address('192.168.0.1') |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 125 | |
| 126 | .. attribute:: version |
| 127 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 128 | The appropriate version number: ``4`` for IPv4, ``6`` for IPv6. |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 129 | |
| 130 | .. attribute:: max_prefixlen |
| 131 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 132 | The total number of bits in the address representation for this |
| 133 | version: ``32`` for IPv4, ``128`` for IPv6. |
| 134 | |
| 135 | The prefix defines the number of leading bits in an address that |
| 136 | are compared to determine whether or not an address is part of a |
| 137 | network. |
| 138 | |
| 139 | .. attribute:: compressed |
| 140 | .. attribute:: exploded |
| 141 | |
| 142 | The string representation in dotted decimal notation. Leading zeroes |
| 143 | are never included in the representation. |
| 144 | |
| 145 | As IPv4 does not define a shorthand notation for addresses with octets |
| 146 | set to zero, these two attributes are always the same as ``str(addr)`` |
| 147 | for IPv4 addresses. Exposing these attributes makes it easier to |
| 148 | write display code that can handle both IPv4 and IPv6 addresses. |
| 149 | |
| 150 | .. attribute:: packed |
| 151 | |
| 152 | The binary representation of this address - a :class:`bytes` object of |
| 153 | the appropriate length (most significant octet first). This is 4 bytes |
| 154 | for IPv4 and 16 bytes for IPv6. |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 155 | |
| 156 | .. attribute:: is_multicast |
| 157 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 158 | ``True`` if the address is reserved for multicast use. See |
| 159 | :RFC:`3171` (for IPv4) or :RFC:`2373` (for IPv6). |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 160 | |
| 161 | .. attribute:: is_private |
| 162 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 163 | ``True`` if the address is allocated for private networks. See |
| 164 | :RFC:`1918` (for IPv4) or :RFC:`4193` (for IPv6). |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 165 | |
| 166 | .. attribute:: is_unspecified |
| 167 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 168 | ``True`` if the address is unspecified. See :RFC:`5375` (for IPv4) |
| 169 | or :RFC:`2373` (for IPv6). |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 170 | |
| 171 | .. attribute:: is_reserved |
| 172 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 173 | ``True`` if the address is otherwise IETF reserved. |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 174 | |
| 175 | .. attribute:: is_loopback |
| 176 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 177 | ``True`` if this is a loopback address. See :RFC:`3330` (for IPv4) |
| 178 | or :RFC:`2373` (for IPv6). |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 179 | |
| 180 | .. attribute:: is_link_local |
| 181 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 182 | ``True`` if the address is reserved for link-local usage. See |
| 183 | :RFC:`3927`. |
| 184 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 185 | |
| 186 | .. class:: IPv6Address(address) |
| 187 | |
| 188 | Construct an IPv6 address. An :exc:`AddressValueError` is raised if |
| 189 | *address* is not a valid IPv6 address. |
| 190 | |
| 191 | The following constitutes a valid IPv6 address: |
| 192 | |
| 193 | 1. A string consisting of eight groups of four hexadecimal digits, each |
| 194 | group representing 16 bits. The groups are separated by colons. |
| 195 | This describes an *exploded* (longhand) notation. The string can |
| 196 | also be *compressed* (shorthand notation) by various means. See |
| 197 | :RFC:`4291` for details. For example, |
| 198 | ``"0000:0000:0000:0000:0000:0abc:0007:0def"`` can be compressed to |
| 199 | ``"::abc:7:def"``. |
| 200 | 2. An integer that fits into 128 bits. |
| 201 | 3. An integer packed into a :class:`bytes` object of length 16, big-endian. |
| 202 | |
| 203 | >>> ipaddress.IPv6Address('2001:db8::1000') |
| 204 | IPv6Address('2001:db8::1000') |
| 205 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 206 | .. attribute:: compressed |
| 207 | |
| 208 | The short form of the address representation, with leading zeroes in |
| 209 | groups omitted and the longest sequence of groups consisting entirely of |
| 210 | zeroes collapsed to a single empty group. |
| 211 | |
| 212 | This is also the value returned by ``str(addr)`` for IPv6 addresses. |
| 213 | |
| 214 | .. attribute:: exploded |
| 215 | |
| 216 | The long form of the address representation, with all leading zeroes and |
| 217 | groups consisting entirely of zeroes included. |
| 218 | |
| 219 | .. attribute:: packed |
| 220 | .. attribute:: version |
| 221 | .. attribute:: max_prefixlen |
| 222 | .. attribute:: is_multicast |
| 223 | .. attribute:: is_private |
| 224 | .. attribute:: is_unspecified |
| 225 | .. attribute:: is_reserved |
| 226 | .. attribute:: is_loopback |
| 227 | .. attribute:: is_link_local |
| 228 | |
| 229 | Refer to the corresponding attribute documentation in |
| 230 | :class:`IPv4Address` |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 231 | |
| 232 | .. attribute:: is_site_local |
| 233 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 234 | ``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 |
| 236 | :attr:`~IPv4Address.is_private` to test if this address is in the |
| 237 | space of unique local addresses as defined by :RFC:`4193`. |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 238 | |
| 239 | .. attribute:: ipv4_mapped |
| 240 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 241 | For addresses that appear to be IPv4 mapped addresses (starting with |
| 242 | ``::FFFF/96``), this property will report the embedded IPv4 address. |
| 243 | For any other address, this property will be ``None``. |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 244 | |
| 245 | .. attribute:: sixtofour |
| 246 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 247 | For addresses that appear to be 6to4 addresses (starting with |
| 248 | ``2002::/16``) as defined by :RFC:`3056`, this property will report |
| 249 | the embedded IPv4 address. For any other address, this property will |
| 250 | be ``None``. |
| 251 | |
| 252 | .. attribute:: teredo |
| 253 | |
| 254 | For addresses that appear to be Teredo addresses (starting with |
| 255 | ``2001::/32``) as defined by :RFC:`4380`, this property will report |
| 256 | the embedded ``(server, client)`` IP address pair. For any other |
| 257 | address, this property will be ``None``. |
| 258 | |
| 259 | |
| 260 | Conversion to Strings and Integers |
| 261 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 262 | |
| 263 | To interoperate with networking interfaces such as the socket module, |
| 264 | addresses must be converted to strings or integers. This is handled using |
| 265 | the :func:`str` and :func:`int` builtin functions:: |
| 266 | |
| 267 | >>> str(ipaddress.IPv4Address('192.168.0.1')) |
| 268 | '192.168.0.1' |
| 269 | >>> int(ipaddress.IPv4Address('192.168.0.1')) |
| 270 | 3232235521 |
| 271 | >>> str(ipaddress.IPv6Address('::1')) |
| 272 | '::1' |
| 273 | >>> int(ipaddress.IPv6Address('::1')) |
| 274 | 1 |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 275 | |
| 276 | |
| 277 | Operators |
| 278 | ^^^^^^^^^ |
| 279 | |
| 280 | Address objects support some operators. Unless stated otherwise, operators can |
| 281 | only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with |
| 282 | IPv6). |
| 283 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 284 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 285 | Logical operators |
| 286 | """"""""""""""""" |
| 287 | |
| 288 | Address objects can be compared with the usual set of logical operators. Some |
| 289 | examples:: |
| 290 | |
| 291 | >>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1') |
| 292 | True |
| 293 | >>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1') |
| 294 | False |
| 295 | >>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1') |
| 296 | True |
| 297 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 298 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 299 | Arithmetic operators |
| 300 | """""""""""""""""""" |
| 301 | |
| 302 | Integers can be added to or subtracted from address objects. Some examples:: |
| 303 | |
| 304 | >>> IPv4Address('127.0.0.2') + 3 |
| 305 | IPv4Address('127.0.0.5') |
| 306 | >>> IPv4Address('127.0.0.2') - 3 |
| 307 | IPv4Address('126.255.255.255') |
| 308 | >>> IPv4Address('255.255.255.255') + 1 |
| 309 | Traceback (most recent call last): |
| 310 | File "<stdin>", line 1, in <module> |
| 311 | ipaddress.AddressValueError: 4294967296 (>= 2**32) is not permitted as an IPv4 address |
| 312 | |
| 313 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 314 | IP Network definitions |
| 315 | ---------------------- |
| 316 | |
| 317 | The :class:`IPv4Network` and :class:`IPv6Network` objects provide a mechanism |
| 318 | for defining and inspecting IP network definitions. A network definition |
| 319 | consists of a *mask* and a *network address*, and as such defines a range of |
| 320 | IP addresses that equal the network address when masked (binary AND) with the |
| 321 | mask. For example, a network definition with the mask ``255.255.255.0`` and |
| 322 | the network address ``192.168.1.0`` consists of IP addresses in the inclusive |
| 323 | range ``192.168.1.0`` to ``192.168.1.255``. |
| 324 | |
| 325 | |
| 326 | Prefix, net mask and host mask |
| 327 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 328 | |
| 329 | There are several equivalent ways to specify IP network masks. A *prefix* |
| 330 | ``/<nbits>`` is a notation that denotes how many high-order bits are set in |
| 331 | the network mask. A *net mask* is an IP address with some number of |
| 332 | high-order bits set. Thus the prefix ``/24`` is equivalent to the net mask |
| 333 | ``255.255.255.0`` in IPv4, or ``ffff:ff00::`` in IPv6. In addition, a |
| 334 | *host mask* is the logical inverse of a *net mask*, and is sometimes used |
| 335 | (for example in Cisco access control lists) to denote a network mask. The |
| 336 | host mask equivalent to ``/24`` in IPv4 is ``0.0.0.255``. |
| 337 | |
| 338 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 339 | Network objects |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 340 | ^^^^^^^^^^^^^^^ |
| 341 | |
| 342 | All attributes implemented by address objects are implemented by network |
| 343 | objects as well. In addition, network objects implement additional attributes. |
| 344 | All of these are common between :class:`IPv4Network` and :class:`IPv6Network`, |
| 345 | so to avoid duplication they are only documented for :class:`IPv4Network`. |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 346 | |
| 347 | .. class:: IPv4Network(address, strict=True) |
| 348 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 349 | Construct an IPv4 network definition. *address* can be one of the following: |
| 350 | |
| 351 | 1. A string consisting of an IP address and an optional mask, separated by |
| 352 | a slash (``/``). The IP address is the network address, and the mask |
| 353 | can be either a single number, which means it's a *prefix*, or a string |
| 354 | representation of an IPv4 address. If it's the latter, the mask is |
| 355 | interpreted as a *net mask* if it starts with a non-zero field, or as |
| 356 | a *host mask* if it starts with a zero field. If no mask is provided, |
| 357 | it's considered to be ``/32``. |
| 358 | |
| 359 | For example, the following *address* specifications are equivalent: |
| 360 | ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and |
| 361 | ``192.168.1.0/0.0.0.255``. |
| 362 | |
| 363 | 2. An integer that fits into 32 bits. This is equivalent to a |
| 364 | single-address network, with the network address being *address* and |
| 365 | the mask being ``/32``. |
| 366 | |
| 367 | 3. An integer packed into a :class:`bytes` object of length 4, big-endian. |
| 368 | The interpretation is similar to an integer *address*. |
| 369 | |
| 370 | An :exc:`AddressValueError` is raised if *address* is not a valid IPv4 |
| 371 | address. A :exc:`NetmaskValueError` is raised if the mask is not valid for |
| 372 | an IPv4 address. |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 373 | |
| 374 | If *strict* is ``True`` and host bits are set in the supplied address, |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 375 | then :exc:`ValueError` is raised. Otherwise, the host bits are masked out |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 376 | to determine the appropriate network address. |
| 377 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 378 | Unless stated otherwise, all network methods accepting other network/address |
| 379 | objects will raise :exc:`TypeError` if the argument's IP version is |
| 380 | incompatible to ``self`` |
| 381 | |
| 382 | .. attribute:: version |
| 383 | .. attribute:: max_prefixlen |
| 384 | |
| 385 | Refer to the corresponding attribute documentation in |
| 386 | :class:`IPv4Address` |
| 387 | |
| 388 | .. attribute:: is_multicast |
| 389 | .. attribute:: is_private |
| 390 | .. attribute:: is_unspecified |
| 391 | .. attribute:: is_reserved |
| 392 | .. attribute:: is_loopback |
| 393 | .. attribute:: is_link_local |
| 394 | |
| 395 | These attributes are true for the network as a whole if they are true |
Terry Jan Reedy | 0f84764 | 2013-03-11 18:34:00 -0400 | [diff] [blame] | 396 | for both the network address and the broadcast address |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 397 | |
| 398 | .. attribute:: network_address |
| 399 | |
Nick Coghlan | 31096a9 | 2012-08-05 22:52:38 +1000 | [diff] [blame] | 400 | The network address for the network. The network address and the |
| 401 | prefix length together uniquely define a network. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 402 | |
| 403 | .. attribute:: broadcast_address |
| 404 | |
Nick Coghlan | 31096a9 | 2012-08-05 22:52:38 +1000 | [diff] [blame] | 405 | The broadcast address for the network. Packets sent to the broadcast |
| 406 | address should be received by every host on the network. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 407 | |
| 408 | .. attribute:: host mask |
| 409 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 410 | The host mask, as a string. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 411 | |
| 412 | .. attribute:: with_prefixlen |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 413 | .. attribute:: compressed |
| 414 | .. attribute:: exploded |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 415 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 416 | A string representation of the network, with the mask in prefix |
| 417 | notation. |
| 418 | |
| 419 | ``with_prefixlen`` and ``compressed`` are always the same as |
| 420 | ``str(network)``. |
| 421 | ``exploded`` uses the exploded form the network address. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 422 | |
| 423 | .. attribute:: with_netmask |
| 424 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 425 | A string representation of the network, with the mask in net mask |
| 426 | notation. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 427 | |
| 428 | .. attribute:: with_hostmask |
| 429 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 430 | A string representation of the network, with the mask in host mask |
| 431 | notation. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 432 | |
| 433 | .. attribute:: num_addresses |
| 434 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 435 | The total number of addresses in the network. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 436 | |
| 437 | .. attribute:: prefixlen |
| 438 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 439 | Length of the network prefix, in bits. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 440 | |
| 441 | .. method:: hosts() |
| 442 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 443 | Returns an iterator over the usable hosts in the network. The usable |
| 444 | hosts are all the IP addresses that belong to the network, except the |
| 445 | network address itself and the network broadcast address. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 446 | |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 447 | >>> list(ip_network('192.0.2.0/29').hosts()) #doctest: +NORMALIZE_WHITESPACE |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 448 | [IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'), |
| 449 | IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'), |
| 450 | IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')] |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 451 | |
| 452 | .. method:: overlaps(other) |
| 453 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 454 | ``True`` if this network is partly or wholly contained in *other* or |
Terry Jan Reedy | 0f84764 | 2013-03-11 18:34:00 -0400 | [diff] [blame] | 455 | *other* is wholly contained in this network. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 456 | |
| 457 | .. method:: address_exclude(network) |
| 458 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 459 | Computes the network definitions resulting from removing the given |
| 460 | *network* from this one. Returns an iterator of network objects. |
| 461 | Raises :exc:`ValueError` if *network* is not completely contained in |
| 462 | this network. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 463 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 464 | >>> n1 = ip_network('192.0.2.0/28') |
| 465 | >>> n2 = ip_network('192.0.2.1/32') |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 466 | >>> list(n1.address_exclude(n2)) #doctest: +NORMALIZE_WHITESPACE |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 467 | [IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'), |
| 468 | IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')] |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 469 | |
| 470 | .. method:: subnets(prefixlen_diff=1, new_prefix=None) |
| 471 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 472 | The subnets that join to make the current network definition, depending |
| 473 | on the argument values. *prefixlen_diff* is the amount our prefix |
| 474 | length should be increased by. *new_prefix* is the desired new |
| 475 | prefix of the subnets; it must be larger than our prefix. One and |
| 476 | only one of *prefixlen_diff* and *new_prefix* must be set. Returns an |
| 477 | iterator of network objects. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 478 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 479 | >>> list(ip_network('192.0.2.0/24').subnets()) |
| 480 | [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')] |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 481 | >>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2)) #doctest: +NORMALIZE_WHITESPACE |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 482 | [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'), |
| 483 | IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')] |
Eli Bendersky | 948af23 | 2012-10-07 07:23:50 -0700 | [diff] [blame] | 484 | >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26)) #doctest: +NORMALIZE_WHITESPACE |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 485 | [IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'), |
| 486 | IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')] |
| 487 | >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23)) |
| 488 | Traceback (most recent call last): |
| 489 | File "<stdin>", line 1, in <module> |
| 490 | raise ValueError('new prefix must be longer') |
| 491 | ValueError: new prefix must be longer |
| 492 | >>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25)) |
| 493 | [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')] |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 494 | |
| 495 | .. method:: supernet(prefixlen_diff=1, new_prefix=None) |
| 496 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 497 | The supernet containing this network definition, depending on the |
| 498 | argument values. *prefixlen_diff* is the amount our prefix length |
| 499 | should be decreased by. *new_prefix* is the desired new prefix of |
| 500 | the supernet; it must be smaller than our prefix. One and only one |
| 501 | of *prefixlen_diff* and *new_prefix* must be set. Returns a single |
| 502 | network object. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 503 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 504 | >>> ip_network('192.0.2.0/24').supernet() |
| 505 | IPv4Network('192.0.2.0/23') |
| 506 | >>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2) |
| 507 | IPv4Network('192.0.0.0/22') |
| 508 | >>> ip_network('192.0.2.0/24').supernet(new_prefix=20) |
| 509 | IPv4Network('192.0.0.0/20') |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 510 | |
| 511 | .. method:: compare_networks(other) |
| 512 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 513 | Compare this network to *other*. In this comparison only the network |
| 514 | addresses are considered; host bits aren't. Returns either ``-1``, |
| 515 | ``0`` or ``1``. |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 516 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 517 | >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32')) |
| 518 | -1 |
| 519 | >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32')) |
| 520 | 1 |
| 521 | >>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32')) |
| 522 | 0 |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 523 | |
| 524 | |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 525 | .. class:: IPv6Network(address, strict=True) |
| 526 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 527 | Construct an IPv6 network definition. *address* can be one of the following: |
| 528 | |
| 529 | 1. A string consisting of an IP address and an optional mask, separated by |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 530 | a slash (``/``). The IP address is the network address, and the mask |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 531 | can be either a single number, which means it's a *prefix*, or a string |
| 532 | representation of an IPv6 address. If it's the latter, the mask is |
| 533 | interpreted as a *net mask*. If no mask is provided, it's considered to |
| 534 | be ``/128``. |
| 535 | |
| 536 | For example, the following *address* specifications are equivalent: |
| 537 | ``2001:db00::0/24`` and ``2001:db00::0/ffff:ff00::``. |
| 538 | |
| 539 | 2. An integer that fits into 128 bits. This is equivalent to a |
| 540 | single-address network, with the network address being *address* and |
| 541 | the mask being ``/128``. |
| 542 | |
| 543 | 3. An integer packed into a :class:`bytes` object of length 16, bit-endian. |
| 544 | The interpretation is similar to an integer *address*. |
| 545 | |
| 546 | An :exc:`AddressValueError` is raised if *address* is not a valid IPv6 |
| 547 | address. A :exc:`NetmaskValueError` is raised if the mask is not valid for |
| 548 | an IPv6 address. |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 549 | |
| 550 | If *strict* is ``True`` and host bits are set in the supplied address, |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 551 | then :exc:`ValueError` is raised. Otherwise, the host bits are masked out |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 552 | to determine the appropriate network address. |
| 553 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 554 | .. attribute:: version |
| 555 | .. attribute:: max_prefixlen |
| 556 | .. attribute:: is_multicast |
| 557 | .. attribute:: is_private |
| 558 | .. attribute:: is_unspecified |
| 559 | .. attribute:: is_reserved |
| 560 | .. attribute:: is_loopback |
| 561 | .. attribute:: is_link_local |
| 562 | .. attribute:: network_address |
| 563 | .. attribute:: broadcast_address |
| 564 | .. attribute:: host mask |
| 565 | .. attribute:: with_prefixlen |
| 566 | .. attribute:: compressed |
| 567 | .. attribute:: exploded |
| 568 | .. attribute:: with_netmask |
| 569 | .. attribute:: with_hostmask |
| 570 | .. attribute:: num_addresses |
| 571 | .. attribute:: prefixlen |
| 572 | .. method:: hosts() |
| 573 | .. method:: overlaps(other) |
| 574 | .. method:: address_exclude(network) |
| 575 | .. method:: subnets(prefixlen_diff=1, new_prefix=None) |
| 576 | .. method:: supernet(prefixlen_diff=1, new_prefix=None) |
| 577 | .. method:: compare_networks(other) |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 578 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 579 | Refer to the corresponding attribute documentation in |
| 580 | :class:`IPv4Network` |
| 581 | |
| 582 | .. attribute:: is_site_local |
| 583 | |
| 584 | These attribute is true for the network as a whole if it is true |
Terry Jan Reedy | 0f84764 | 2013-03-11 18:34:00 -0400 | [diff] [blame] | 585 | for both the network address and the broadcast address |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 586 | |
| 587 | |
| 588 | Operators |
| 589 | ^^^^^^^^^ |
| 590 | |
| 591 | Network objects support some operators. Unless stated otherwise, operators can |
| 592 | only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with |
| 593 | IPv6). |
| 594 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 595 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 596 | Logical operators |
| 597 | """"""""""""""""" |
| 598 | |
| 599 | Network objects can be compared with the usual set of logical operators, |
| 600 | similarly to address objects. |
| 601 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 602 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 603 | Iteration |
| 604 | """"""""" |
| 605 | |
| 606 | Network objects can be iterated to list all the addresses belonging to the |
| 607 | network. For iteration, *all* hosts are returned, including unusable hosts |
| 608 | (for usable hosts, use the :meth:`~IPv4Network.hosts` method). An |
| 609 | example:: |
| 610 | |
| 611 | >>> for addr in IPv4Network('192.0.2.0/28'): |
| 612 | ... addr |
| 613 | ... |
| 614 | IPv4Address('192.0.2.0') |
| 615 | IPv4Address('192.0.2.1') |
| 616 | IPv4Address('192.0.2.2') |
| 617 | IPv4Address('192.0.2.3') |
| 618 | IPv4Address('192.0.2.4') |
| 619 | IPv4Address('192.0.2.5') |
| 620 | IPv4Address('192.0.2.6') |
| 621 | IPv4Address('192.0.2.7') |
| 622 | IPv4Address('192.0.2.8') |
| 623 | IPv4Address('192.0.2.9') |
| 624 | IPv4Address('192.0.2.10') |
| 625 | IPv4Address('192.0.2.11') |
| 626 | IPv4Address('192.0.2.12') |
| 627 | IPv4Address('192.0.2.13') |
| 628 | IPv4Address('192.0.2.14') |
| 629 | IPv4Address('192.0.2.15') |
| 630 | |
Nick Coghlan | 7362c3e | 2012-08-05 22:32:37 +1000 | [diff] [blame] | 631 | |
Nick Coghlan | 730f67f | 2012-08-05 22:02:18 +1000 | [diff] [blame] | 632 | Networks as containers of addresses |
| 633 | """"""""""""""""""""""""""""""""""" |
| 634 | |
| 635 | Network objects can act as containers of addresses. Some examples:: |
| 636 | |
| 637 | >>> IPv4Network('192.0.2.0/28')[0] |
| 638 | IPv4Address('192.0.2.0') |
| 639 | >>> IPv4Network('192.0.2.0/28')[15] |
| 640 | IPv4Address('192.0.2.15') |
| 641 | >>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28') |
| 642 | True |
| 643 | >>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28') |
| 644 | False |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 645 | |
| 646 | |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 647 | Interface objects |
| 648 | ----------------- |
| 649 | |
| 650 | .. class:: IPv4Interface(address) |
| 651 | |
Nick Coghlan | a8517ad | 2012-08-20 10:04:26 +1000 | [diff] [blame] | 652 | Construct an IPv4 interface. The meaning of *address* is as in the |
| 653 | constructor of :class:`IPv4Network`, except that arbitrary host addresses |
| 654 | are always accepted. |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 655 | |
Nick Coghlan | a8517ad | 2012-08-20 10:04:26 +1000 | [diff] [blame] | 656 | :class:`IPv4Interface` is a subclass of :class:`IPv4Address`, so it inherits |
| 657 | all the attributes from that class. In addition, the following attributes |
| 658 | are available: |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 659 | |
Nick Coghlan | a8517ad | 2012-08-20 10:04:26 +1000 | [diff] [blame] | 660 | .. attribute:: ip |
| 661 | |
| 662 | The address (:class:`IPv4Address`) without network information. |
| 663 | |
| 664 | >>> interface = IPv4Interface('192.0.2.5/24') |
| 665 | >>> interface.ip |
| 666 | IPv4Address('192.0.2.5') |
| 667 | |
| 668 | .. attribute:: network |
| 669 | |
| 670 | The network (:class:`IPv4Network`) this interface belongs to. |
| 671 | |
| 672 | >>> interface = IPv4Interface('192.0.2.5/24') |
| 673 | >>> interface.network |
| 674 | IPv4Network('192.0.2.0/24') |
| 675 | |
| 676 | .. attribute:: with_prefixlen |
| 677 | |
| 678 | A string representation of the interface with the mask in prefix notation. |
| 679 | |
| 680 | >>> interface = IPv4Interface('192.0.2.5/24') |
| 681 | >>> interface.with_prefixlen |
| 682 | '192.0.2.5/24' |
| 683 | |
| 684 | .. attribute:: with_netmask |
| 685 | |
| 686 | A string representation of the interface with the network as a net mask. |
| 687 | |
| 688 | >>> interface = IPv4Interface('192.0.2.5/24') |
| 689 | >>> interface.with_netmask |
| 690 | '192.0.2.5/255.255.255.0' |
| 691 | |
| 692 | .. attribute:: with_hostmask |
| 693 | |
| 694 | A string representation of the interface with the network as a host mask. |
| 695 | |
| 696 | >>> interface = IPv4Interface('192.0.2.5/24') |
| 697 | >>> interface.with_hostmask |
| 698 | '192.0.2.5/0.0.0.255' |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 699 | |
| 700 | |
| 701 | .. class:: IPv6Interface(address) |
| 702 | |
Nick Coghlan | a8517ad | 2012-08-20 10:04:26 +1000 | [diff] [blame] | 703 | Construct an IPv6 interface. The meaning of *address* is as in the |
| 704 | constructor of :class:`IPv6Network`, except that arbitrary host addresses |
| 705 | are always accepted. |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 706 | |
Nick Coghlan | a8517ad | 2012-08-20 10:04:26 +1000 | [diff] [blame] | 707 | :class:`IPv6Interface` is a subclass of :class:`IPv6Address`, so it inherits |
| 708 | all the attributes from that class. In addition, the following attributes |
| 709 | are available: |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 710 | |
Nick Coghlan | a8517ad | 2012-08-20 10:04:26 +1000 | [diff] [blame] | 711 | .. attribute:: ip |
| 712 | .. attribute:: network |
| 713 | .. attribute:: with_prefixlen |
| 714 | .. attribute:: with_netmask |
| 715 | .. attribute:: with_hostmask |
| 716 | |
| 717 | Refer to the corresponding attribute documentation in |
| 718 | :class:`IPv4Interface`. |
Eli Bendersky | 0e49749 | 2012-07-31 17:23:11 +0300 | [diff] [blame] | 719 | |
| 720 | |
Nick Coghlan | 9680bdb | 2012-06-17 17:24:10 +1000 | [diff] [blame] | 721 | Other Module Level Functions |
| 722 | ---------------------------- |
| 723 | |
| 724 | The module also provides the following module level functions: |
| 725 | |
| 726 | .. function:: v4_int_to_packed(address) |
| 727 | |
| 728 | Represent an address as 4 packed bytes in network (big-endian) order. |
| 729 | *address* is an integer representation of an IPv4 IP address. A |
| 730 | :exc:`ValueError` is raised if the integer is negative or too large to be an |
| 731 | IPv4 IP address. |
| 732 | |
| 733 | >>> ipaddress.ip_address(3221225985) |
| 734 | IPv4Address('192.0.2.1') |
| 735 | >>> ipaddress.v4_int_to_packed(3221225985) |
| 736 | b'\xc0\x00\x02\x01' |
| 737 | |
| 738 | |
| 739 | .. function:: v6_int_to_packed(address) |
| 740 | |
| 741 | Represent an address as 16 packed bytes in network (big-endian) order. |
| 742 | *address* is an integer representation of an IPv6 IP address. A |
| 743 | :exc:`ValueError` is raised if the integer is negative or too large to be an |
| 744 | IPv6 IP address. |
| 745 | |
| 746 | |
| 747 | .. function:: summarize_address_range(first, last) |
| 748 | |
| 749 | Return an iterator of the summarized network range given the first and last |
| 750 | IP addresses. *first* is the first :class:`IPv4Address` or |
| 751 | :class:`IPv6Address` in the range and *last* is the last :class:`IPv4Address` |
| 752 | or :class:`IPv6Address` in the range. A :exc:`TypeError` is raised if |
| 753 | *first* or *last* are not IP addresses or are not of the same version. A |
| 754 | :exc:`ValueError` is raised if *last* is not greater than *first* or if |
| 755 | *first* address version is not 4 or 6. |
| 756 | |
| 757 | >>> [ipaddr for ipaddr in ipaddress.summarize_address_range( |
| 758 | ... ipaddress.IPv4Address('192.0.2.0'), |
| 759 | ... ipaddress.IPv4Address('192.0.2.130'))] |
| 760 | [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')] |
| 761 | |
| 762 | |
| 763 | .. function:: collapse_addresses(addresses) |
| 764 | |
| 765 | Return an iterator of the collapsed :class:`IPv4Network` or |
| 766 | :class:`IPv6Network` objects. *addresses* is an iterator of |
| 767 | :class:`IPv4Network` or :class:`IPv6Network` objects. A :exc:`TypeError` is |
| 768 | raised if *addresses* contains mixed version objects. |
| 769 | |
| 770 | >>> [ipaddr for ipaddr in |
| 771 | ... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'), |
| 772 | ... ipaddress.IPv4Network('192.0.2.128/25')])] |
| 773 | [IPv4Network('192.0.2.0/24')] |
| 774 | |
| 775 | |
| 776 | .. function:: get_mixed_type_key(obj) |
| 777 | |
| 778 | Return a key suitable for sorting between networks and addresses. Address |
| 779 | and Network objects are not sortable by default; they're fundamentally |
| 780 | different, so the expression:: |
| 781 | |
| 782 | IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24') |
| 783 | |
| 784 | doesn't make sense. There are some times however, where you may wish to |
| 785 | have :mod:`ipaddress` sort these anyway. If you need to do this, you can use |
| 786 | this function as the ``key`` argument to :func:`sorted()`. |
| 787 | |
| 788 | *obj* is either a network or address object. |
| 789 | |
| 790 | |
| 791 | Custom Exceptions |
| 792 | ----------------- |
| 793 | |
| 794 | To support more specific error reporting from class constructors, the |
| 795 | module defines the following exceptions: |
| 796 | |
| 797 | .. exception:: AddressValueError(ValueError) |
| 798 | |
| 799 | Any value error related to the address. |
| 800 | |
| 801 | |
| 802 | .. exception:: NetmaskValueError(ValueError) |
| 803 | |
| 804 | Any value error related to the netmask. |