From 19acc54ae7fca3b8d7a161663d87eb7d104a532e Mon Sep 17 00:00:00 2001 From: Nicholas Sim Date: Mon, 27 Feb 2023 21:25:21 +0800 Subject: [PATCH] bpo-18280: Remove first-person usage for some docs Additionally: clean up the text explanation for one mock example which this commit touches. --- Doc/extending/extending.rst | 6 ++---- Doc/howto/clinic.rst | 2 +- Doc/howto/functional.rst | 9 ++++----- Doc/howto/sockets.rst | 4 ---- Doc/library/doctest.rst | 4 ++-- Doc/library/heapq.rst | 5 ++--- Doc/library/imaplib.rst | 3 ++- Doc/library/unittest.mock-examples.rst | 11 +++++------ 8 files changed, 18 insertions(+), 26 deletions(-) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index d9bf4fd6c7ae0e..7862cf9335f59e 100644 --- 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 diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst index 8a10fe327358c0..b8a513f0ecc3d2 100644 --- a/Doc/howto/clinic.rst +++ b/Doc/howto/clinic.rst @@ -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 index 38a651b0f964a6..d7d387b8b4215d 100644 --- 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 index 0bbf97da39768d..b389bcde3e8ac8 100644 --- 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 index d6e4dca0860671..956f9d457681a0 100644 --- 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 diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index 8b00f7b27959b6..18413d4de5677c 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -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! :-) diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst index f1344ae9bb0a49..8d17189c873f98 100644 --- a/Doc/library/imaplib.rst +++ b/Doc/library/imaplib.rst @@ -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 index f9a207bad6903f..e9be1d91746b27 100644 --- 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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy