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

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

5 files changed, 26 insertions, 4 deletions

diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst
index ec2a7eb..4bc3956 100644
--- 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 dc7dce9..5193990 100644
--- 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 b564722..6764e0d 100755
--- 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 648e18d..bbd0c06 100644
--- 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
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.