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