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