PEP 788: Minor editorial fixes (#4477)

ZeroIntensity · web-flow · commit c5fc5a4f9bfd · 2025-07-02T09:29:08.000+02:00
* Clarify that weak references cannot be promoted postmortem.
* Get rid of 'plethora'.
* Clarify that PyInterpreterWeakRef_AsStrong() does not set an exception.
* Add some clarity to 'A Library Interface'
* Clarify that PyInterpreterWeakRef will always be pointer-sized.
* Add quote links to 'Daemon Threads Are Not the Problem'
diff --git a/peps/pep-0788.rst b/peps/pep-0788.rst
@@ -181,7 +181,8 @@ Prior to this PEP, deprecating daemon threads was discussed
 `extensively <https://discuss.python.org/t/68836>`_. Daemon threads technically
 cause many of the issues outlined in this proposal, so removing daemon threads
 could be seen as a potential solution. The main argument for removing daemon
-threads is that they're a large cause of problems in the interpreter:
+threads is that they're a large cause of problems in the interpreter
+`[1] <https://discuss.python.org/t/68836/6>`_.
 
     Except that daemon threads don’t actually work reliably. They’re attempting
     to run and use Python interpreter resources after the runtime has been shut
@@ -190,7 +191,8 @@ threads is that they're a large cause of problems in the interpreter:
 
 However, in practice, daemon threads are useful for simplifying many threading
 applications in Python, and since the program is about to close in most cases,
-it's not worth the added complexity to try and gracefully shut down a thread.
+it's not worth the added complexity to try and gracefully shut down a thread
+`[2] <https://discuss.python.org/t/68836/3>`_.
 
     When I’ve needed daemon threads, it’s usually been the case of “Long-running,
     uninterruptible, third-party task” in terms of the examples in the linked issue.
@@ -205,7 +207,8 @@ As noted by this PEP, extension modules are free to create their own threads
 and attach thread states for them. Similar to daemon threads, Python doesn't
 try and join them during finalization, so trying to remove daemon threads
 as a whole would involve trying to remove them from the C API, which would
-require a much more massive API change.
+require a much more massive API change than what is currently being proposed
+`[3] <https://discuss.python.org/t/68836/7>`_.
 
     Realize however that even if we get rid of daemon threads, extension
     module code can and does spawn its own threads that are not tracked by
@@ -379,20 +382,23 @@ Weak References
 
 This proposal also comes with weak references to an interpreter that don't
 prevent it from shutting down, but can be promoted to a strong reference when
-the user decides that they want to call the C API.  A weak reference will
-typically live much longer than a strong reference. This is useful for many of
-the asynchronous situations stated previously, where the thread itself
-shouldn't prevent the desired interpreter from shutting down, but also allow
-the thread to execute Python when needed.
+the user decides that they want to call the C API.  If an interpreter is
+destroyed or past the point where it can create strong references, promotion
+of a weak reference will fail.
+
+A weak reference will typically live much longer than a strong reference.
+This is useful for many of the asynchronous situations stated previously,
+where the thread itself shouldn't prevent the desired interpreter from shutting
+down, but also allow the thread to execute Python when needed.
 
 For example, a (non-reentrant) event handler may store a weak interpreter
 reference in its ``void *arg`` parameter, and then that weak reference will
 be promoted to a strong reference when it's time to call Python code.
 
-Deprecation of the GIL-state APIs
----------------------------------
+Removing the outdated GIL-state APIs
+------------------------------------
 
-Due to the plethora of issues with ``PyGILState``, this PEP intends to do away
+Due to the unfixable issues with ``PyGILState``, this PEP intends to do away
 with them entirely. In today's C API, all ``PyGILState`` functions are
 replaceable with ``PyThreadState`` counterparts that are compatibile with
 subinterpreters:
@@ -507,6 +513,8 @@ Weak Interpreter References
     The interpreter will *not* wait for the reference to be
     released before shutting down.
 
+    This type is guaranteed to be pointer-sized.
+
 .. c:function:: int PyInterpreterWeakRef_Get(PyInterpreterWeakRef *wref)
 
     Acquire a weak reference to the current interpreter.
@@ -535,7 +543,8 @@ Weak Interpreter References
     reference to the interpreter denoted by *wref*.
 
     If the interpreter no longer exists or has already finished waiting
-    for its reference count to reach zero, then this function returns ``-1``.
+    for its reference count to reach zero, then this function returns ``-1``
+    without an exception set.
 
     This function is not safe to call in a re-entrant signal handler.
 
@@ -679,8 +688,8 @@ If you were to use :c:func:`PyGILState_Ensure` for this case, then your
 thread would hang if the interpreter were to be finalizing at that time!
 
 Additionally, the API supports subinterpreters. If you were to assume that
-the main interpreter created the file object, then your library wouldn't be safe to use
-with file objects created by a subinterpreter.
+the main interpreter created the file object (via :c:func:`PyGILState_Ensure`),
+then using file objects owned by a subinterpreter could possibly crash.
 
 Example: A Single-threaded Ensure
 *********************************
