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>

diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst
index 9c2dff55703273ffa21d86c113b4aa473b912652..1de36b643c4dca60381556e3543d12c35fb62940 100644 (file)
--- a/Doc/library/ipaddress.rst
+++ b/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
 

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index f2c14415febab995f836604662f38aa27ddf9c97..e12c2a1b0454fd982cae74ea4f04f937a15e4b93 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/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
 ------
 

diff --git a/Lib/ipaddress.py b/Lib/ipaddress.py
index 68ddfbeb4bc212808841c3b7ff2cc941123055a0..e398cc138308d934cf67eb8bd12e6d15929804b9 100644 (file)
--- a/Lib/ipaddress.py
+++ b/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):
 

diff --git a/Lib/test/test_ipaddress.py b/Lib/test/test_ipaddress.py
index 33a0f9894a32f999e96d33f9dfdf8c30da5eed7c..b4952acc2b61b1e5ec63f4680ed89e4e01ec98dc 100644 (file)
--- a/Lib/test/test_ipaddress.py
+++ b/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

diff --git a/Misc/NEWS.d/next/Library/2023-09-15-12-30-21.gh-issue-109466.6ah-aw.rst b/Misc/NEWS.d/next/Library/2023-09-15-12-30-21.gh-issue-109466.6ah-aw.rst
new file mode 100644 (file)
index 0000000..e8e5be3
--- /dev/null
+++ b/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.\r