gh-116349: Deprecate `platform.java_ver` function (#116471)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index ec2a7ebd5d6e0b1af537309f1a1b512131497ceb..4bc3956449b930d6e2c8a02694c8e7c185bf3832 100644 (file)
--- a/Doc/library/platform.rst
+++ b/Doc/library/platform.rst
@@ -196,6 +196,10 @@ Java Platform
    ``(os_name, os_version, os_arch)``. Values which cannot be determined are set to
    the defaults given as parameters (which all default to ``''``).
 
+   .. deprecated-removed:: 3.13 3.15
+      It was largely untested, had a confusing API,
+      and was only useful for Jython support.
+
 
 Windows Platform
 ----------------

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index dc7dce969a695a4ab9257e3bda371edef532b84d..519399090009602f894c4afe0c211c5f5a7f8a9c 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -814,6 +814,10 @@ Deprecated
 * The undocumented and unused ``tarfile`` attribute of :class:`tarfile.TarFile`
   is deprecated and scheduled for removal in Python 3.16.
 
+* :func:`platform.java_ver` is deprecated and will be removed in 3.15.
+  It was largely untested, had a confusing API,
+  and was only useful for Jython support.
+  (Contributed by Nikita Sobolev in :gh:`116349`.)
 
 Pending Removal in Python 3.14
 ------------------------------
@@ -973,6 +977,11 @@ Pending Removal in Python 3.15
   They will be removed in Python 3.15.
   (Contributed by Victor Stinner in :gh:`105096`.)
 
+* :func:`platform.java_ver` is deprecated and will be removed in 3.15.
+  It was largely untested, had a confusing API,
+  and was only useful for Jython support.
+  (Contributed by Nikita Sobolev in :gh:`116349`.)
+
 Pending Removal in Python 3.16
 ------------------------------
 

diff --git a/Lib/platform.py b/Lib/platform.py
index b56472235ee9e420a1d93bcbc594541907dcb8f9..6764e0d5f75063b993719d9d648bcb679757bed1 100755 (executable)
--- a/Lib/platform.py
+++ b/Lib/platform.py
@@ -503,7 +503,7 @@ def mac_ver(release='', versioninfo=('', '', ''), machine=''):
     return release, versioninfo, machine
 
 def _java_getprop(name, default):
-
+    """This private helper is deprecated in 3.13 and will be removed in 3.15"""
     from java.lang import System
     try:
         value = System.getProperty(name)
@@ -525,6 +525,8 @@ def java_ver(release='', vendor='', vminfo=('', '', ''), osinfo=('', '', '')):
         given as parameters (which all default to '').
 
     """
+    import warnings
+    warnings._deprecated('java_ver', remove=(3, 15))
     # Import the needed APIs
     try:
         import java.lang

diff --git a/Lib/test/test_platform.py b/Lib/test/test_platform.py
index 648e18d0150ef08d228b23d2c82f352fe2e1c116..bbd0c06efed2c98417be0e678bf5318793174d73 100644 (file)
--- a/Lib/test/test_platform.py
+++ b/Lib/test/test_platform.py
@@ -318,9 +318,13 @@ class PlatformTest(unittest.TestCase):
                     platform._uname_cache = None
 
     def test_java_ver(self):
-        res = platform.java_ver()
-        if sys.platform == 'java':  # Is never actually checked in CI
-            self.assertTrue(all(res))
+        import re
+        msg = re.escape(
+            "'java_ver' is deprecated and slated for removal in Python 3.15"
+        )
+        with self.assertWarnsRegex(DeprecationWarning, msg):
+            res = platform.java_ver()
+        self.assertEqual(len(res), 4)
 
     def test_win32_ver(self):
         res = platform.win32_ver()

diff --git a/Misc/NEWS.d/next/Library/2024-03-07-21-57-50.gh-issue-116349.fD2pbP.rst b/Misc/NEWS.d/next/Library/2024-03-07-21-57-50.gh-issue-116349.fD2pbP.rst
new file mode 100644 (file)
index 0000000..89eb419
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2024-03-07-21-57-50.gh-issue-116349.fD2pbP.rst
@@ -0,0 +1,3 @@
+:func:`platform.java_ver` is deprecated and will be removed in 3.15.
+It was largely untested, had a confusing API,
+and was only useful for Jython support.