python · nw0 · Feb 27, 2023
diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
@@ -883,10 +883,8 @@ is stored somewhere, and which is decremented when a reference to it is deleted.
 When the counter reaches zero, the last reference to the object has been deleted
 and the object is freed.
 
-An alternative strategy is called :dfn:`automatic garbage collection`.
-(Sometimes, reference counting is also referred to as a garbage collection
-strategy, hence my use of "automatic" to distinguish the two.)  The big
-advantage of automatic garbage collection is that the user doesn't need to call
+An alternative strategy to refernce counting is :dfn:`garbage collection`.
+The main advantage of garbage collection is that the programmer need not call
 :c:func:`free` explicitly.  (Another claimed advantage is an improvement in speed
 or memory usage --- this is no hard fact however.)  The disadvantage is that for
 C, there is no truly portable automatic garbage collector, while reference

@@ -161,7 +161,7 @@ Let's dive in!
 1. Find a Python builtin that calls either :c:func:`PyArg_ParseTuple`
    or :c:func:`PyArg_ParseTupleAndKeywords`, and hasn't been converted
    to work with Argument Clinic yet.
-   For my example I'm using ``_pickle.Pickler.dump()``.
+   This example refers to ``_pickle.Pickler.dump()``.
 
 2. If the call to the ``PyArg_Parse`` function uses any of the
    following format units:

diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
@@ -1131,12 +1131,11 @@ usual way::
     def print_assign(name, value):
         return name + '=' + str(value)
 
-Which alternative is preferable?  That's a style question; my usual course is to
-avoid using ``lambda``.
+Which alternative is preferable?  As a rule of thumb, ``lambda`` should be
+avoided for complex expressions.
 
-One reason for my preference is that ``lambda`` is quite limited in the
-functions it can define.  The result has to be computable as a single
-expression, which means you can't have multiway ``if... elif... else``
+The reason is that ``lambda`` can only evaluate and return a single expression.
+This means you can't have multiway ``if... elif... else``
 comparisons or ``try... except`` statements.  If you try to do too much in a
 ``lambda`` statement, you'll end up with an overly complicated expression that's
 hard to read.  Quick, what's the following code doing? ::

diff --git a/Doc/howto/sockets.rst b/Doc/howto/sockets.rst
@@ -243,10 +243,6 @@ This is also when you'll discover that ``send`` does not always manage to get
 rid of everything in one pass. And despite having read this, you will eventually
 get bit by it!
 
-In the interests of space, building your character, (and preserving my
-competitive position), these enhancements are left as an exercise for the
-reader. Lets move on to cleaning up.
-
 
 Binary Data
 -----------

diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
@@ -1808,8 +1808,8 @@ this that needs to be learned---it may not be natural at first.  Examples should
 add genuine value to the documentation.  A good example can often be worth many
 words. If done with care, the examples will be invaluable for your users, and
 will pay back the time it takes to collect them many times over as the years go
-by and things change.  I'm still amazed at how often one of my :mod:`doctest`
-examples stops working after a "harmless" change.
+by and code changes.  Well-written :mod:`doctest` examples can be especially
+helpful to detect unintended changes to an API.
 
 Doctest also makes an excellent tool for regression testing, especially if you
 don't skimp on explanatory text.  By interleaving prose and examples, it becomes

@@ -278,8 +278,7 @@ last 0'th element you extracted.  This is especially useful in simulation
 contexts, where the tree holds all incoming events, and the "win" condition
 means the smallest scheduled time.  When an event schedules other events for
 execution, they are scheduled into the future, so they can easily go into the
-heap.  So, a heap is a good structure for implementing schedulers (this is what
-I used for my MIDI sequencer :-).
+heap.  So, a heap is suitable for implementing a scheduler.
 
 Various structures for implementing schedulers have been extensively studied,
 and heaps are good for this, as they are reasonably speedy, the speed is almost
@@ -316,7 +315,7 @@ applications, and I think it is good to keep a 'heap' module around. :-)
    different, and one had to be very clever to ensure (far in advance) that each
    tape movement will be the most effective possible (that is, will best
    participate at "progressing" the merge).  Some tapes were even able to read
-   backwards, and this was also used to avoid the rewinding time. Believe me, real
+   backwards, and this was also used to avoid the rewinding time. Real
    good tape sorts were quite spectacular to watch! From all times, sorting has
    always been a Great Art! :-)
 
@@ -350,7 +350,8 @@ An :class:`IMAP4` instance has the following methods:
 
 .. method:: IMAP4.myrights(mailbox)
 
-   Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
+   Show ACLs for a mailbox (i.e. the rights which the authenticated user has
+   on the mailbox).
 
 
 .. method:: IMAP4.namespace()

diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst
@@ -835,13 +835,12 @@ One possibility would be for mock to copy the arguments you pass in. This
 could then cause problems if you do assertions that rely on object identity
 for equality.
 
-Here's one solution that uses the :attr:`side_effect`
+Here's one solution using the :attr:`side_effect`
 functionality. If you provide a ``side_effect`` function for a mock then
-``side_effect`` will be called with the same args as the mock. This gives us an
-opportunity to copy the arguments and store them for later assertions. In this
-example I'm using *another* mock to store the arguments so that I can use the
-mock methods for doing the assertion. Again a helper function sets this up for
-me. ::
+``side_effect`` will be called with the same args as the mock. This gives an
+opportunity to copy the arguments and store them for later assertions.
+The following example uses *another* Mock, ``new_mock``, to store the
+arguments so that they can later be compared with ``assert_called_with``. ::
 
     >>> from copy import deepcopy
     >>> from unittest.mock import Mock, patch, DEFAULT