[Python-checkins] bpo-18802: Add more details to ipaddress documentation (GH-6083)

Tue Mar 20 20:30:46 EDT 2018

https://github.com/python/cpython/commit/a323eee4c481c88f2b4030bbb224d9bc6bc14c9c
commit: a323eee4c481c88f2b4030bbb224d9bc6bc14c9c
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018年03月20日T17:30:43-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 76177a0b23eb..935add17e2c8 100644
--- a/Doc/library/ipaddress.rst
+++ b/Doc/library/ipaddress.rst
@@ -91,7 +91,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)
 
@@ -368,6 +369,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)
 
@@ -377,8 +380,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:
@@ -408,7 +412,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
 
@@ -418,7 +422,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
@@ -428,7 +432,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
 
@@ -590,10 +594,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::``
@@ -652,12 +656,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
@@ -671,8 +675,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
@@ -722,6 +726,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
@@ -793,6 +800,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
 ----------------------------
 
@@ -858,7 +889,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.
 
@@ -876,4 +907,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 dbf68b3f8f1a..a5aeb790faeb 100644
--- a/Lib/test/test_ipaddress.py
+++ b/Lib/test/test_ipaddress.py
@@ -404,6 +404,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.
