gh-109466: Add ipv6_mapped property to IPv4Address (#109467)

Adds the `IPv4Address.ipv6_mapped` property.

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

Doc/library/ipaddress.rst

@@ -219,6 +219,13 @@ write code that handles both IP versions correctly.  Address objects are
       ``True`` if the address is reserved for link-local usage.  See
       :RFC:`3927`.
 
+   .. attribute:: ipv6_mapped
+
+      :class:`IPv4Address` object representing the IPv4-mapped IPv6 address. See :RFC:`4291`.
+
+      .. versionadded:: 3.13
+
+
 .. _iana-ipv4-special-registry: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
 .. _iana-ipv6-special-registry: https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
 

Doc/whatsnew/3.13.rst

@@ -185,6 +185,12 @@ and only logged in :ref:`Python Development Mode <devmode>` or on :ref:`Python
 built on debug mode <debug-build>`.
 (Contributed by Victor Stinner in :gh:`62948`.)
 
+ipaddress
+---------
+
+* Add the :attr:`ipaddress.IPv4Address.ipv6_mapped` property, which returns the IPv4-mapped IPv6 address.
+  (Contributed by Charles Machalow in :gh:`109466`.)
+
 opcode
 ------
 

Lib/ipaddress.py

@@ -1389,6 +1389,16 @@ class IPv4Address(_BaseV4, _BaseAddress):
         """
         return self in self._constants._linklocal_network
 
+    @property
+    def ipv6_mapped(self):
+        """Return the IPv4-mapped IPv6 address.
+
+        Returns:
+            The IPv4-mapped IPv6 address per RFC 4291.
+
+        """
+        return IPv6Address(f'::ffff:{self}')
+
 
 class IPv4Interface(IPv4Address):
 

Lib/test/test_ipaddress.py

@@ -303,6 +303,14 @@ class AddressTestCase_v4(BaseTestCase, CommonTestMixin_v4):
     def test_weakref(self):
         weakref.ref(self.factory('192.0.2.1'))
 
+    def test_ipv6_mapped(self):
+        self.assertEqual(ipaddress.IPv4Address('192.168.1.1').ipv6_mapped,
+                         ipaddress.IPv6Address('::ffff:192.168.1.1'))
+        self.assertEqual(ipaddress.IPv4Address('192.168.1.1').ipv6_mapped,
+                         ipaddress.IPv6Address('::ffff:c0a8:101'))
+        self.assertEqual(ipaddress.IPv4Address('192.168.1.1').ipv6_mapped.ipv4_mapped,
+                         ipaddress.IPv4Address('192.168.1.1'))
+
 
 class AddressTestCase_v6(BaseTestCase, CommonTestMixin_v6):
     factory = ipaddress.IPv6Address

Misc/NEWS.d/next/Library/2023-09-15-12-30-21.gh-issue-109466.6ah-aw.rst

@@ -0,0 +1 @@
+Add the :attr:`ipaddress.IPv4Address.ipv6_mapped` property, which retuns the IPv4-mapped IPv6 address.