Merge branch 'main' into cleanup/315/remove-cgi-handler-133810

Author: picnixz

Doc/deprecations/pending-removal-in-3.15.rst

@@ -51,7 +51,7 @@ Pending removal in Python 3.15
 
 * :mod:`platform`:
 
-  * :func:`~platform.java_ver` has been deprecated since Python 3.13.
+  * :func:`!platform.java_ver` has been deprecated since Python 3.13.
     This function is only useful for Jython support, has a confusing API,
     and is largely untested.
 

Doc/library/platform.rst

@@ -188,24 +188,6 @@ Cross platform
       :attr:`processor` is resolved late instead of immediately.
 
 
-Java platform
--------------
-
-
-.. function:: java_ver(release='', vendor='', vminfo=('','',''), osinfo=('','',''))
-
-   Version interface for Jython.
-
-   Returns a tuple ``(release, vendor, vminfo, osinfo)`` with *vminfo* being a
-   tuple ``(vm_name, vm_release, vm_vendor)`` and *osinfo* being a tuple
-   ``(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
 ----------------
 

Doc/library/threading.rst

@@ -11,6 +11,52 @@
 This module constructs higher-level threading interfaces on top of the lower
 level :mod:`_thread` module.
 
+.. include:: ../includes/wasm-notavail.rst
+
+Introduction
+------------
+
+The :mod:`!threading` module provides a way to run multiple `threads
+<https://en.wikipedia.org/wiki/Thread_(computing)>`_ (smaller
+units of a process) concurrently within a single process. It allows for the
+creation and management of threads, making it possible to execute tasks in
+parallel, sharing memory space. Threads are particularly useful when tasks are
+I/O bound, such as file operations or making network requests,
+where much of the time is spent waiting for external resources.
+
+A typical use case for :mod:`!threading` includes managing a pool of worker
+threads that can process multiple tasks concurrently.  Here's a basic example of
+creating and starting threads using :class:`~threading.Thread`::
+
+   import threading
+   import time
+
+   def crawl(link, delay=3):
+       print(f"crawl started for {link}")
+       time.sleep(delay)  # Blocking I/O (simulating a network request)
+       print(f"crawl ended for {link}")
+
+   links = [
+       "https://python.org",
+       "https://docs.python.org",
+       "https://peps.python.org",
+   ]
+
+   # Start threads for each link
+   threads = []
+   for link in links:
+       # Using `args` to pass positional arguments and `kwargs` for keyword arguments
+       t = threading.Thread(target=crawl, args=(link,), kwargs={"delay": 2})
+       threads.append(t)
+
+   # Start each thread
+   for t in threads:
+       t.start()
+
+   # Wait for all threads to finish
+   for t in threads:
+       t.join()
+
 .. versionchanged:: 3.7
    This module used to be optional, it is now always available.
 
@@ -45,7 +91,25 @@ level :mod:`_thread` module.
    However, threading is still an appropriate model if you want to run
    multiple I/O-bound tasks simultaneously.
 
-.. include:: ../includes/wasm-notavail.rst
+GIL and performance considerations
+----------------------------------
+
+Unlike the :mod:`multiprocessing` module, which uses separate processes to
+bypass the :term:`global interpreter lock` (GIL), the threading module operates
+within a single process, meaning that all threads share the same memory space.
+However, the GIL limits the performance gains of threading when it comes to
+CPU-bound tasks, as only one thread can execute Python bytecode at a time.
+Despite this, threads remain a useful tool for achieving concurrency in many
+scenarios.
+
+As of Python 3.13, experimental :term:`free-threaded <free threading>` builds
+can disable the GIL, enabling true parallel execution of threads, but this
+feature is not available by default (see :pep:`703`).
+
+.. TODO: At some point this feature will become available by default.
+
+Reference
+---------
 
 This module defines the following functions:
 
@@ -62,7 +126,7 @@ This module defines the following functions:
 
    Return the current :class:`Thread` object, corresponding to the caller's thread
    of control.  If the caller's thread of control was not created through the
-   :mod:`threading` module, a dummy thread object with limited functionality is
+   :mod:`!threading` module, a dummy thread object with limited functionality is
    returned.
 
    The function ``currentThread`` is a deprecated alias for this function.
@@ -157,13 +221,13 @@ This module defines the following functions:
 
    .. index:: single: trace function
 
-   Set a trace function for all threads started from the :mod:`threading` module.
+   Set a trace function for all threads started from the :mod:`!threading` module.
    The *func* will be passed to  :func:`sys.settrace` for each thread, before its
    :meth:`~Thread.run` method is called.
 
 .. function:: settrace_all_threads(func)
 
-   Set a trace function for all threads started from the :mod:`threading` module
+   Set a trace function for all threads started from the :mod:`!threading` module
    and all Python threads that are currently executing.
 
    The *func* will be passed to  :func:`sys.settrace` for each thread, before its
@@ -186,13 +250,13 @@ This module defines the following functions:
 
    .. index:: single: profile function
 
-   Set a profile function for all threads started from the :mod:`threading` module.
+   Set a profile function for all threads started from the :mod:`!threading` module.
    The *func* will be passed to  :func:`sys.setprofile` for each thread, before its
    :meth:`~Thread.run` method is called.
 
 .. function:: setprofile_all_threads(func)
 
-   Set a profile function for all threads started from the :mod:`threading` module
+   Set a profile function for all threads started from the :mod:`!threading` module
    and all Python threads that are currently executing.
 
    The *func* will be passed to  :func:`sys.setprofile` for each thread, before its
@@ -257,8 +321,8 @@ when implemented, are mapped to module-level functions.
 All of the methods described below are executed atomically.
 
 
-Thread-Local Data
------------------
+Thread-local data
+^^^^^^^^^^^^^^^^^
 
 Thread-local data is data whose values are thread specific. If you
 have data that you want to be local to a thread, create a
@@ -389,8 +453,8 @@ affects what we see::
 
 .. _thread-objects:
 
-Thread Objects
---------------
+Thread objects
+^^^^^^^^^^^^^^
 
 The :class:`Thread` class represents an activity that is run in a separate
 thread of control.  There are two ways to specify the activity: by passing a
@@ -645,8 +709,8 @@ since it is impossible to detect the termination of alien threads.
 
 .. _lock-objects:
 
-Lock Objects
-------------
+Lock objects
+^^^^^^^^^^^^
 
 A primitive lock is a synchronization primitive that is not owned by a
 particular thread when locked.  In Python, it is currently the lowest level
@@ -738,8 +802,8 @@ All methods are executed atomically.
 
 .. _rlock-objects:
 
-RLock Objects
--------------
+RLock objects
+^^^^^^^^^^^^^
 
 A reentrant lock is a synchronization primitive that may be acquired multiple
 times by the same thread.  Internally, it uses the concepts of "owning thread"
@@ -848,8 +912,8 @@ call release as many times the lock has been acquired can lead to deadlock.
 
 .. _condition-objects:
 
-Condition Objects
------------------
+Condition objects
+^^^^^^^^^^^^^^^^^
 
 A condition variable is always associated with some kind of lock; this can be
 passed in or one will be created by default.  Passing one in is useful when
@@ -1026,8 +1090,8 @@ item to the buffer only needs to wake up one consumer thread.
 
 .. _semaphore-objects:
 
-Semaphore Objects
------------------
+Semaphore objects
+^^^^^^^^^^^^^^^^^
 
 This is one of the oldest synchronization primitives in the history of computer
 science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
@@ -1107,7 +1171,7 @@ Semaphores also support the :ref:`context management protocol <with-locks>`.
 
 .. _semaphore-examples:
 
-:class:`Semaphore` Example
+:class:`Semaphore` example
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Semaphores are often used to guard resources with limited capacity, for example,
@@ -1135,8 +1199,8 @@ causes the semaphore to be released more than it's acquired will go undetected.
 
 .. _event-objects:
 
-Event Objects
--------------
+Event objects
+^^^^^^^^^^^^^
 
 This is one of the simplest mechanisms for communication between threads: one
 thread signals an event and other threads wait for it.
@@ -1192,8 +1256,8 @@ method.  The :meth:`~Event.wait` method blocks until the flag is true.
 
 .. _timer-objects:
 
-Timer Objects
--------------
+Timer objects
+^^^^^^^^^^^^^
 
 This class represents an action that should be run only after a certain amount
 of time has passed --- a timer.  :class:`Timer` is a subclass of :class:`Thread`
@@ -1230,8 +1294,8 @@ For example::
       only work if the timer is still in its waiting stage.
 
 
-Barrier Objects
----------------
+Barrier objects
+^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.2
 

Doc/whatsnew/3.13.rst

@@ -1908,7 +1908,7 @@ New Deprecations
 
 * :mod:`platform`:
 
-  * Deprecate :func:`~platform.java_ver`,
+  * Deprecate :func:`!platform.java_ver`,
     to be removed in Python 3.15.
     This function is only useful for Jython support, has a confusing API,
     and is largely untested.

Doc/whatsnew/3.15.rst

@@ -130,6 +130,14 @@ http.server
   (Contributed by Bénédikt Tran in :gh:`133810`.)
 
 
+platform
+--------
+
+* Removed the :func:`!platform.java_ver` function,
+  which was deprecated since Python 3.13.
+  (Contributed by Alexey Makridenko in :gh:`133604`.)
+
+
 sysconfig
 ---------
 

Lib/platform.py

@@ -29,7 +29,7 @@
 #
 #    History:
 #
-#    <see CVS and SVN checkin messages for history>
+#    <see checkin messages for history>
 #
 #    1.0.9 - added invalidate_caches() function to invalidate cached values
 #    1.0.8 - changed Windows support to read version from kernel32.dll
@@ -110,7 +110,7 @@
 
 """
 
-__version__ = '1.0.9'
+__version__ = '1.1.0'
 
 import collections
 import os
@@ -528,53 +528,6 @@ def ios_ver(system="", release="", model="", is_simulator=False):
     return IOSVersionInfo(system, release, model, is_simulator)
 
 
-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)
-        if value is None:
-            return default
-        return value
-    except AttributeError:
-        return default
-
-def java_ver(release='', vendor='', vminfo=('', '', ''), osinfo=('', '', '')):
-
-    """ Version interface for Jython.
-
-        Returns a tuple (release, vendor, vminfo, osinfo) with vminfo being
-        a tuple (vm_name, vm_release, vm_vendor) and osinfo being a
-        tuple (os_name, os_version, os_arch).
-
-        Values which cannot be determined are set to the defaults
-        given as parameters (which all default to '').
-
-    """
-    import warnings
-    warnings._deprecated('java_ver', remove=(3, 15))
-    # Import the needed APIs
-    try:
-        import java.lang  # noqa: F401
-    except ImportError:
-        return release, vendor, vminfo, osinfo
-
-    vendor = _java_getprop('java.vendor', vendor)
-    release = _java_getprop('java.version', release)
-    vm_name, vm_release, vm_vendor = vminfo
-    vm_name = _java_getprop('java.vm.name', vm_name)
-    vm_vendor = _java_getprop('java.vm.vendor', vm_vendor)
-    vm_release = _java_getprop('java.vm.version', vm_release)
-    vminfo = vm_name, vm_release, vm_vendor
-    os_name, os_version, os_arch = osinfo
-    os_arch = _java_getprop('java.os.arch', os_arch)
-    os_name = _java_getprop('java.os.name', os_name)
-    os_version = _java_getprop('java.os.version', os_version)
-    osinfo = os_name, os_version, os_arch
-
-    return release, vendor, vminfo, osinfo
-
-
 AndroidVer = collections.namedtuple(
     "AndroidVer", "release api_level manufacturer model device is_emulator")
 
@@ -1034,13 +987,6 @@ def uname():
                     version = '16bit'
             system = 'Windows'
 
-        elif system[:4] == 'java':
-            release, vendor, vminfo, osinfo = java_ver()
-            system = 'Java'
-            version = ', '.join(vminfo)
-            if not version:
-                version = vendor
-
     # System specific extensions
     if system == 'OpenVMS':
         # OpenVMS seems to have release and version mixed up
@@ -1370,15 +1316,6 @@ def platform(aliased=False, terse=False):
         platform = _platform(system, release, machine, processor,
                              'with',
                              libcname+libcversion)
-    elif system == 'Java':
-        # Java platforms
-        r, v, vminfo, (os_name, os_version, os_arch) = java_ver()
-        if terse or not os_name:
-            platform = _platform(system, release, version)
-        else:
-            platform = _platform(system, release, version,
-                                 'on',
-                                 os_name, os_version, os_arch)
 
     else:
         # Generic handler