[Python-checkins] bpo-18802: Add more details to ipaddress documentation (GH-6083)
Miss Islington (bot)
webhook-mailer at python.org
Tue Mar 20 20:59:03 EDT 2018
https://github.com/python/cpython/commit/481cbe8d6202658a7908d97f19f7e9e6061e3df3
commit: 481cbe8d6202658a7908d97f19f7e9e6061e3df3
branch: 3.6
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018-03-20T17:59:00-07:00
summary:
bpo-18802: Add more details to ipaddress documentation (GH-6083)
Original patch by Jon Foster and Berker Peksag.
(cherry picked from commit 5609b78392d59c7362ef8aa5c4a4529325f01f27)
Co-authored-by: Cheryl Sabella <cheryl.sabella at gmail.com>
files:
A Misc/NEWS.d/next/Documentation/2018-03-11-18-53-47.bpo-18802.JhAqH3.rst
M Doc/library/ipaddress.rst
M Lib/test/test_ipaddress.py
diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst
index b3c691e444a1..66c1aaa6a181 100644
--- a/Doc/library/ipaddress.rst
+++ b/Doc/library/ipaddress.rst
@@ -89,7 +89,8 @@ Address objects
The :class:`IPv4Address` and :class:`IPv6Address` objects share a lot of common
attributes. Some attributes that are only meaningful for IPv6 addresses are
also implemented by :class:`IPv4Address` objects, in order to make it easier to
-write code that handles both IP versions correctly.
+write code that handles both IP versions correctly. Address objects are
+:term:`hashable`, so they can be used as keys in dictionaries.
.. class:: IPv4Address(address)
@@ -366,6 +367,8 @@ All attributes implemented by address objects are implemented by network
objects as well. In addition, network objects implement additional attributes.
All of these are common between :class:`IPv4Network` and :class:`IPv6Network`,
so to avoid duplication they are only documented for :class:`IPv4Network`.
+Network objects are :term:`hashable`, so they can be used as keys in
+dictionaries.
.. class:: IPv4Network(address, strict=True)
@@ -375,8 +378,9 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
a slash (``/``). The IP address is the network address, and the mask
can be either a single number, which means it's a *prefix*, or a string
representation of an IPv4 address. If it's the latter, the mask is
- interpreted as a *net mask* if it starts with a non-zero field, or as
- a *host mask* if it starts with a zero field. If no mask is provided,
+ interpreted as a *net mask* if it starts with a non-zero field, or as a
+ *host mask* if it starts with a zero field, with the single exception of
+ an all-zero mask which is treated as a *net mask*. If no mask is provided,
it's considered to be ``/32``.
For example, the following *address* specifications are equivalent:
@@ -406,7 +410,7 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
Unless stated otherwise, all network methods accepting other network/address
objects will raise :exc:`TypeError` if the argument's IP version is
- incompatible to ``self``
+ incompatible to ``self``.
.. versionchanged:: 3.5
@@ -416,7 +420,7 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
.. attribute:: max_prefixlen
Refer to the corresponding attribute documentation in
- :class:`IPv4Address`
+ :class:`IPv4Address`.
.. attribute:: is_multicast
.. attribute:: is_private
@@ -426,7 +430,7 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
.. attribute:: is_link_local
These attributes are true for the network as a whole if they are true
- for both the network address and the broadcast address
+ for both the network address and the broadcast address.
.. attribute:: network_address
@@ -563,10 +567,10 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
Construct an IPv6 network definition. *address* can be one of the following:
- 1. A string consisting of an IP address and an optional mask, separated by
- a slash (``/``). The IP address is the network address, and the mask
- is a single number, which represents a *prefix*. If no mask is provided,
- it's considered to be ``/128``.
+ 1. A string consisting of an IP address and an optional prefix length,
+ separated by a slash (``/``). The IP address is the network address,
+ and the prefix length must be a single number, the *prefix*. If no
+ prefix length is provided, it's considered to be ``/128``.
Note that currently expanded netmasks are not supported. That means
``2001:db00::0/24`` is a valid argument while ``2001:db00::0/ffff:ff00::``
@@ -623,12 +627,12 @@ so to avoid duplication they are only documented for :class:`IPv4Network`.
.. method:: compare_networks(other)
Refer to the corresponding attribute documentation in
- :class:`IPv4Network`
+ :class:`IPv4Network`.
.. attribute:: is_site_local
These attribute is true for the network as a whole if it is true
- for both the network address and the broadcast address
+ for both the network address and the broadcast address.
Operators
@@ -642,8 +646,8 @@ IPv6).
Logical operators
"""""""""""""""""
-Network objects can be compared with the usual set of logical operators,
-similarly to address objects.
+Network objects can be compared with the usual set of logical operators.
+Network objects are ordered first by network address, then by net mask.
Iteration
@@ -693,6 +697,9 @@ Network objects can act as containers of addresses. Some examples::
Interface objects
-----------------
+Interface objects are :term:`hashable`, so they can be used as keys in
+dictionaries.
+
.. class:: IPv4Interface(address)
Construct an IPv4 interface. The meaning of *address* is as in the
@@ -764,6 +771,30 @@ Interface objects
:class:`IPv4Interface`.
+Operators
+^^^^^^^^^
+
+Interface objects support some operators. Unless stated otherwise, operators
+can only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with
+IPv6).
+
+
+Logical operators
+"""""""""""""""""
+
+Interface objects can be compared with the usual set of logical operators.
+
+For equality comparison (``==`` and ``!=``), both the IP address and network
+must be the same for the objects to be equal. An interface will not compare
+equal to any address or network object.
+
+For ordering (``<``, ``>``, etc) the rules are different. Interface and
+address objects with the same IP version can be compared, and the address
+objects will always sort before the interface objects. Two interface objects
+are first compared by their networks and, if those are the same, then by their
+IP addresses.
+
+
Other Module Level Functions
----------------------------
@@ -829,7 +860,7 @@ The module also provides the following module level functions:
doesn't make sense. There are some times however, where you may wish to
have :mod:`ipaddress` sort these anyway. If you need to do this, you can use
- this function as the ``key`` argument to :func:`sorted()`.
+ this function as the *key* argument to :func:`sorted()`.
*obj* is either a network or address object.
@@ -847,4 +878,4 @@ module defines the following exceptions:
.. exception:: NetmaskValueError(ValueError)
- Any value error related to the netmask.
+ Any value error related to the net mask.
diff --git a/Lib/test/test_ipaddress.py b/Lib/test/test_ipaddress.py
index 5d9633024f70..2432eb4960e1 100644
--- a/Lib/test/test_ipaddress.py
+++ b/Lib/test/test_ipaddress.py
@@ -405,6 +405,9 @@ def test_weakref(self):
class NetmaskTestMixin_v4(CommonTestMixin_v4):
"""Input validation on interfaces and networks is very similar"""
+ def test_no_mask(self):
+ self.assertEqual(str(self.factory('1.2.3.4')), '1.2.3.4/32')
+
def test_split_netmask(self):
addr = "1.2.3.4/32/24"
with self.assertAddressError("Only one '/' permitted in %r" % addr):
diff --git a/Misc/NEWS.d/next/Documentation/2018-03-11-18-53-47.bpo-18802.JhAqH3.rst b/Misc/NEWS.d/next/Documentation/2018-03-11-18-53-47.bpo-18802.JhAqH3.rst
new file mode 100644
index 000000000000..cb9cc2599aca
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-03-11-18-53-47.bpo-18802.JhAqH3.rst
@@ -0,0 +1 @@
+Documentation changes for ipaddress. Patch by Jon Foster and Berker Peksag.
More information about the Python-checkins
mailing list