fixup! PEP 748: shutdown(show: 0|1|2) instead of close(force: bool)

Author: Julien00859

peps/pep-0748.rst

@@ -468,42 +468,19 @@ The following code describes these functions in more detail:
             """
             Shutdown TLS and the underlying socket.
 
-            Proper TLS applications ought to signal their peers when they're
-            done sending data by sending a closing alert.
-
-            * ``socket.SHUT_WR`` (``1``) sends the closing alert to the peer and
-              then prevents sending any further message. Proper TLS application
-              **MUST** call this method with this parameter to gracefully close
-              the TLS connection. *Safe* in TLS 1.3. Actually acts like
-              ``SHUT_RDWD`` in TLS 1.2 and is as *unsafe* as ``SHUT_RD``.
-
-            * ``socket.SHUT_RD`` (``0``) simulates receiving the closing alert
-              from the peer and then ignores all further received messages.
-              *Unsafe* (risk of data loss) unless the connection is otherwise
-              known to be over thanks to the application-layer protocol (e.g.
-              HTTP Content-Length).
-
-            * ``socket.SHUT_RDWR`` (``2``) does both ``SHUT_RD`` and ``SHUT_WR``.
-              As *unsafe* as ``SHUT_RD``.
-
-            In TLS 1.2, the closing alert is synchronous, receiving it triggers
-            an immediate closing alert response, and both connections are
-            immediately shut. It means that ``SHUT_WR`` acts like ``SHUT_RDWR``
-            and is unsafe unless all the data have been received.
-
-            In TLS 1.3, the closing alert is asynchronous, sending the closing
-            alert only closes the sender's sending-end and receiver's
-            receiving-end. The peer can keep on sending data until he
-            independently decides to close its own sending-end of the
-            connection. There is not risk of data truncation with ``SHUT_WR``.
+            * ``socket.SHUT_RD`` (``0``) unilateraly close the receiving-side:
+              discard present and future unread messages.
+            * ``socket.SHUT_WR`` (``1``) gracefully close the sending-side:
+              send a closing alert and prevent sending more messages.
+            * ``socket.SHUT_RDWR`` (``2``): both ``SHUT_WR`` and ``SHUT_RD``.
 
             .. danger::
 
-                Both ``socket.SHUT_RD`` (``0``) and ``socket.SHUT_RDWR`` (``2``)
-                pose a risk of data loss, only use them when facing a bad actor
-                or when the connection is otherwise known to be over.
+                Both ``shutdown(SHUT_RD)`` and ``shutdown(SHUT_RDWR)`` pose a
+                risk of data loss: they are unsafe unless the connection is
+                otherwise known to be over or when truncation is not an issue.
 
-                In TLS 1.2 the same risk applies also to ``socket.SHUT_WR`` (``1``).
+                In TLS 1.2, the same risk applies also to ``shutdown(SHUT_WR)``.
             """
             ...
 
@@ -512,15 +489,15 @@ The following code describes these functions in more detail:
             """
             Close the underlying socket, but only when it is safe to do so.
 
-            When the sending-end of the connection is still open, it sends a
-            closing alert before closing the socket, raising ``WantWriteError``
-            when it fails.
+            When the sending-side of the connection is still open, it gracefully
+            closes the TLS sending-side before closing the socket, raising
+            ``WantWriteError`` when it fails.
 
-            When the receiving-end of the connection is still open, it always
+            When the receiving-side of the connection is still open, it always
             raises ``WantReadError`` as there's a risk of data loss / truncation
             attack. The user must first either: (safe) ``recv`` until the peer
-            closes its sending-end of the connection, or (unsafe) take the risk
-            and unilateraly ``shutdown`` the reading-end of the connection.
+            closes its sending-side of the connection, or (unsafe) take the risk
+            and unilateraly ``shutdown`` the receiving-side of the connection.
             """
             ...