Issue #14814: document the Interface APIs and fix various problems with the string representations (initial patch by Eli Bendersky).

3 files changed, 72 insertions, 30 deletions

diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst
index fea1724..1046828 100644
--- a/Doc/library/ipaddress.rst
+++ b/Doc/library/ipaddress.rst
@@ -642,32 +642,73 @@ Interface objects
 
 .. class:: IPv4Interface(address)
 
-   Construct an IPv4 interface.  *address* is a string or integer representing
-   the IP interface.  An :exc:`AddressValueError` is raised if *address* is not
-   a valid IPv4 address.
+   Construct an IPv4 interface.  The meaning of *address* is as in the
+   constructor of :class:`IPv4Network`, except that arbitrary host addresses
+   are always accepted.
 
-   The network address for the interface is determined by calling
-   ``IPv4Network(address, strict=False)``.
+   :class:`IPv4Interface` is a subclass of :class:`IPv4Address`, so it inherits
+   all the attributes from that class.  In addition, the following attributes
+   are available:
 
-   >>> ipaddress.IPv4Interface('192.168.0.0/24')
-   IPv4Interface('192.168.0.0/24')
-   >>> ipaddress.IPv4Interface('192.168.0.0/24').network
-   IPv4Network('192.168.0.0/24')
+   .. attribute:: ip
+
+      The address (:class:`IPv4Address`) without network information.
+
+         >>> interface = IPv4Interface('192.0.2.5/24')
+         >>> interface.ip
+         IPv4Address('192.0.2.5')
+
+   .. attribute:: network
+
+      The network (:class:`IPv4Network`) this interface belongs to.
+
+         >>> interface = IPv4Interface('192.0.2.5/24')
+         >>> interface.network
+         IPv4Network('192.0.2.0/24')
+
+   .. attribute:: with_prefixlen
+
+      A string representation of the interface with the mask in prefix notation.
+
+         >>> interface = IPv4Interface('192.0.2.5/24')
+         >>> interface.with_prefixlen
+         '192.0.2.5/24'
+
+   .. attribute:: with_netmask
+
+      A string representation of the interface with the network as a net mask.
+
+         >>> interface = IPv4Interface('192.0.2.5/24')
+         >>> interface.with_netmask
+         '192.0.2.5/255.255.255.0'
+
+   .. attribute:: with_hostmask
+
+      A string representation of the interface with the network as a host mask.
+
+         >>> interface = IPv4Interface('192.0.2.5/24')
+         >>> interface.with_hostmask
+         '192.0.2.5/0.0.0.255'
 
 
 .. class:: IPv6Interface(address)
 
-   Construct an IPv6 interface.  *address* is a string or integer representing
-   the IP interface.  An :exc:`AddressValueError` is raised if *address* is not
-   a valid IPv6 address.
+   Construct an IPv6 interface.  The meaning of *address* is as in the
+   constructor of :class:`IPv6Network`, except that arbitrary host addresses
+   are always accepted.
 
-   The network address for the interface is determined by calling
-   ``IPv6Network(address, strict=False)``.
+   :class:`IPv6Interface` is a subclass of :class:`IPv6Address`, so it inherits
+   all the attributes from that class.  In addition, the following attributes
+   are available:
 
-   >>> ipaddress.IPv6Interface('2001:db8::1000/96')
-   IPv6Interface('2001:db8::1000/96')
-   >>> ipaddress.IPv6Interface('2001:db8::1000/96').network
-   IPv6Network('2001:db8::/96')
+   .. attribute:: ip
+   .. attribute:: network
+   .. attribute:: with_prefixlen
+   .. attribute:: with_netmask
+   .. attribute:: with_hostmask
+
+      Refer to the corresponding attribute documentation in
+      :class:`IPv4Interface`.
 
 
 Other Module Level Functions
diff --git a/Lib/ipaddress.py b/Lib/ipaddress.py
index c9338c5..cfc370c 100644
--- a/Lib/ipaddress.py
+++ b/Lib/ipaddress.py
@@ -1336,7 +1336,8 @@ class IPv4Interface(IPv4Address):
 
     @property
     def with_prefixlen(self):
-        return self
+        return '%s/%s' % (self._string_from_ip_int(self._ip),
+                          self._prefixlen)
 
     @property
     def with_netmask(self):
@@ -1948,11 +1949,13 @@ class IPv6Interface(IPv6Address):
 
     @property
     def with_prefixlen(self):
-        return self
+        return '%s/%s' % (self._string_from_ip_int(self._ip),
+                          self._prefixlen)
 
     @property
     def with_netmask(self):
-        return self.with_prefixlen
+        return '%s/%s' % (self._string_from_ip_int(self._ip),
+                          self.netmask)
 
     @property
     def with_hostmask(self):
diff --git a/Lib/test/test_ipaddress.py b/Lib/test/test_ipaddress.py
index 09b4a5e..99c54f1 100644
--- a/Lib/test/test_ipaddress.py
+++ b/Lib/test/test_ipaddress.py
@@ -1558,21 +1558,19 @@ class IpaddrUnitTest(unittest.TestCase):
         self.assertEqual(ipaddress.IPv6Network(1).version, 6)
 
     def testWithStar(self):
-        self.assertEqual(str(self.ipv4_interface.with_prefixlen), "1.2.3.4/24")
-        self.assertEqual(str(self.ipv4_interface.with_netmask),
+        self.assertEqual(self.ipv4_interface.with_prefixlen, "1.2.3.4/24")
+        self.assertEqual(self.ipv4_interface.with_netmask,
                          "1.2.3.4/255.255.255.0")
-        self.assertEqual(str(self.ipv4_interface.with_hostmask),
+        self.assertEqual(self.ipv4_interface.with_hostmask,
                          "1.2.3.4/0.0.0.255")
 
-        self.assertEqual(str(self.ipv6_interface.with_prefixlen),
-                         '2001:658:22a:cafe:200::1/64')
-        # rfc3513 sec 2.3 says that ipv6 only uses cidr notation for
-        # subnets
-        self.assertEqual(str(self.ipv6_interface.with_netmask),
+        self.assertEqual(self.ipv6_interface.with_prefixlen,
                          '2001:658:22a:cafe:200::1/64')
+        self.assertEqual(self.ipv6_interface.with_netmask,
+                         '2001:658:22a:cafe:200::1/ffff:ffff:ffff:ffff::')
         # this probably don't make much sense, but it's included for
         # compatibility with ipv4
-        self.assertEqual(str(self.ipv6_interface.with_hostmask),
+        self.assertEqual(self.ipv6_interface.with_hostmask,
                          '2001:658:22a:cafe:200::1/::ffff:ffff:ffff:ffff')
 
     def testNetworkElementCaching(self):