gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst #100270

bskinn · 2022-12-15T15:38:06Z

Another docs revision PR of asyncio-eventloop.rst per #85747.

There are a couple of spots here where I think more explanation than was already present will be useful. I've attempted explanations of my own, but they may be incorrect. I'll mark these with review comments shortly.

I didn't change much of the passive voice related to callback interactions, within the description text of methods that work with callbacks. All the attempts I made to cast those descriptions in active voice seemed to degrade readability.

Issue: Please use active voice in async docs. #85747

Loop run/stop section, and callbacks section.

netlify · 2022-12-15T15:38:12Z

✅ Deploy Preview for python-cpython-preview ready!

Name	Link
🔨 Latest commit	`7c3fb58`
🔍 Latest deploy log	https://app.netlify.com/sites/python-cpython-preview/deploys/639b3f604a5a2b000a14de44
😎 Deploy Preview	https://deploy-preview-100270--python-cpython-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

Doc/library/asyncio-eventloop.rst

CAM-Gerlach

I've added some clarifications on some further points of confusion (that I had to look up in the code, or guess on), as well as refined the phrasing and fixed a few other issues. Thanks!

Doc/library/asyncio-eventloop.rst

gvanrossum · 2022-12-18T16:59:32Z

I'm unsubscribing for now, but do ping me if you need me to arbitrate some choice!

Co-authored-by: C.A.M. Gerlach <[email protected]>

Doc/library/asyncio-eventloop.rst

I also prefer the more verbose phrasing that doesn't start the sentence with a lowercase letter. Remove the spurious whitespace. Co-authored-by: Guido van Rossum <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>

@gvanrossum

Per @gvanrossum: https://github.com/python/cpython/pull/100270/files#r1057825172

bskinn · 2023-02-02T05:10:24Z

@gvanrossum -- I believe this PR is ready for consideration for merge. Thank you for the input & guidance!

gvanrossum

I'm sorry, but there are still too many grammatical oddities to approve the PR. Please ask one of the docs folks (e.g. @CAM-Gerlach) to go over the grammar carefully.

bedevere-bot · 2023-02-04T19:26:53Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

arhadthedev · 2023-02-04T19:32:21Z

Please ask one of the docs folks [...] to go over the grammar carefully.

@python/proofreaders

CAM-Gerlach

After some more consideration and thought, various suggestions to improve the readability and clarity of the grammar and phrasing and avoid regressions on that front.

Doc/library/asyncio-eventloop.rst

terryjreedy · 2023-02-05T01:38:17Z

I am taking a look,

Doc/library/asyncio-eventloop.rst

bskinn · 2023-02-06T14:21:51Z

@CAM-Gerlach, it seems like you and @terryjreedy are in a good flow for further polishing here.

Do you have write access on my fork? If not, do you want it? I don't want my pace of review to hold up applying changes to the PR branch.

Co-authored-by: Terry Jan Reedy <[email protected]>

CAM-Gerlach · 2023-02-06T23:26:18Z

Thanks @bskinn . I've applied the review comments and also moved the return line up to right after the call_soon summary line, as mentioned above.

Just FYI, you can just batch-apply all desired review comments in one go by clicking on the Files changed, clicking Add to batch on each suggestion, and finally pressing Commit.

bskinn · 2023-02-06T23:28:05Z

Just FYI, you can just batch-apply all desired review comments in one go by clicking on the Files changed, clicking Add to batch on each suggestion, and finally pressing Commit.

Yup, I know -- super handy feature! I wasn't sure which suggestions were 'final', or if there was more discussion coming...so, I didn't feel comfortable committing anything without a thorough review that I couldn't be sure when I could carry out.

CAM-Gerlach

LGTM from my end, now

miss-islington · 2023-02-07T05:25:46Z

Thanks @bskinn for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

miss-islington · 2023-02-07T05:26:05Z

Sorry, @bskinn and @gvanrossum, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker c4de6b1d52304a0a9cdfafc1dad5098993710404 3.11

miss-islington · 2023-02-07T05:26:07Z

Sorry @bskinn and @gvanrossum, I had trouble checking out the 3.10 backport branch.
Please retry by removing and re-adding the "needs backport to 3.10" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker c4de6b1d52304a0a9cdfafc1dad5098993710404 3.10

bedevere-bot · 2023-02-17T22:24:12Z

GH-102005 is a backport of this pull request to the 3.10 branch.

bedevere-bot · 2023-02-17T22:32:28Z

GH-102006 is a backport of this pull request to the 3.11 branch.

…ing loop' & 'callbacks' subsections of asyncio-eventloop.rst (pythonGH-100270) Co-authored-by: C.A.M. Gerlach <[email protected]> Co-authored-by: Terry Jan Reedy <[email protected]>. (cherry picked from commit c4de6b1) Co-authored-by: Brian Skinn <[email protected]>

…op' & 'callbacks' subsections of asyncio-eventloop.rst (GH-100270) (#102006) Note: the `timeout` parameter was not added until 3.12. (cherry picked from commit c4de6b1) Co-authored-by: C.A.M. Gerlach <[email protected]> Co-authored-by: Terry Jan Reedy <[email protected]>. Co-authored-by: Brian Skinn <[email protected]>

…op' & 'callbacks' subsections of asyncio-eventloop.rst (gh-100270) (#102005) Note: The `timeout` parameter was not added until Python 3.12. (cherry picked from commit c4de6b1) Co-authored-by: C.A.M. Gerlach <[email protected]> Co-authored-by: Terry Jan Reedy <[email protected]>

Apply first pass edits

7c3fb58

Loop run/stop section, and callbacks section.

bskinn requested review from 1st1, asvetlov, gvanrossum and kumaraditya303 as code owners December 15, 2022 15:38

bedevere-bot mentioned this pull request Dec 15, 2022

Please use active voice in async docs. #85747

Closed

bedevere-bot added the awaiting review label Dec 15, 2022

bedevere-bot added docs Documentation in the Doc dir skip news labels Dec 15, 2022

bskinn commented Dec 15, 2022

View reviewed changes

Doc/library/asyncio-eventloop.rst Outdated Show resolved Hide resolved

bskinn commented Dec 15, 2022

View reviewed changes

Doc/library/asyncio-eventloop.rst Outdated Show resolved Hide resolved

CAM-Gerlach reviewed Dec 16, 2022

View reviewed changes

bskinn and others added 3 commits December 27, 2022 08:09

Fix ThreadPoolExecutor cross-ref

2184a23

Co-authored-by: C.A.M. Gerlach <[email protected]>

Apply suggestions from code review

a0193d7

Co-authored-by: C.A.M. Gerlach <[email protected]>

Convert note to directive & switch to 'method'

a72b858

Co-authored-by: C.A.M. Gerlach <[email protected]>

CAM-Gerlach reviewed Dec 27, 2022

View reviewed changes

Doc/library/asyncio-eventloop.rst Outdated Show resolved Hide resolved

gvanrossum reviewed Dec 28, 2022

View reviewed changes

Doc/library/asyncio-eventloop.rst Outdated Show resolved Hide resolved

bskinn and others added 4 commits January 31, 2023 20:52

Apply suggestions from code review

012e840

I also prefer the more verbose phrasing that doesn't start the sentence with a lowercase letter. Remove the spurious whitespace. Co-authored-by: Guido van Rossum <[email protected]> Co-authored-by: C.A.M. Gerlach <[email protected]>

Revert edit to call_soon() docs

7d18a15

Per @gvanrossum: https://github.com/python/cpython/pull/100270/files#r1057825172

Apply Guido's wording for call_soon_threadsafe()

eb0834b

Merge branch 'main' into active-voice-asyncio-2

53c4620

kumaraditya303 requested a review from gvanrossum February 3, 2023 09:58

gvanrossum requested changes Feb 4, 2023

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Feb 4, 2023

CAM-Gerlach self-requested a review February 4, 2023 23:37

CAM-Gerlach added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Feb 4, 2023

CAM-Gerlach reviewed Feb 5, 2023

View reviewed changes

terryjreedy requested changes Feb 5, 2023

View reviewed changes

Doc/library/asyncio-eventloop.rst Outdated Show resolved Hide resolved

Doc/library/asyncio-eventloop.rst Outdated Show resolved Hide resolved

Doc/library/asyncio-eventloop.rst Outdated Show resolved Hide resolved

CAM-Gerlach and others added 2 commits February 6, 2023 17:02

Apply further review suggestions to refine phrasing

5898d77

Co-authored-by: Terry Jan Reedy <[email protected]>

Move call_soon return line after summary & explictly ref thread-safe

ffc2187

CAM-Gerlach requested review from terryjreedy and gvanrossum February 6, 2023 23:26

CAM-Gerlach approved these changes Feb 6, 2023

View reviewed changes

gvanrossum merged commit c4de6b1 into python:main Feb 7, 2023

bedevere-bot removed the awaiting changes label Feb 7, 2023

miss-islington assigned gvanrossum Feb 7, 2023

bskinn mentioned this pull request Feb 17, 2023

[3.10] gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst (gh-100270) #102005

Merged

bedevere-bot removed the needs backport to 3.10 only security fixes label Feb 17, 2023

bskinn mentioned this pull request Feb 17, 2023

[3.11] gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst (GH-100270) #102006

Merged

bedevere-bot removed the needs backport to 3.11 only security fixes label Feb 17, 2023

bskinn deleted the active-voice-asyncio-2 branch February 18, 2023 23:59

Uh oh!

gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst #100270

gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst #100270

Uh oh!

Conversation

bskinn commented Dec 15, 2022 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Dec 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for python-cpython-preview ready!

Uh oh!

Uh oh!

Uh oh!

CAM-Gerlach left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gvanrossum commented Dec 18, 2022

Uh oh!

Uh oh!

Uh oh!

bskinn commented Feb 2, 2023

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Feb 4, 2023

Uh oh!

arhadthedev commented Feb 4, 2023

Uh oh!

CAM-Gerlach left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

terryjreedy commented Feb 5, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bskinn commented Feb 6, 2023

Uh oh!

CAM-Gerlach commented Feb 6, 2023

Uh oh!

bskinn commented Feb 6, 2023

Uh oh!

CAM-Gerlach left a comment

Choose a reason for hiding this comment

Uh oh!

miss-islington commented Feb 7, 2023

Uh oh!

miss-islington commented Feb 7, 2023

Uh oh!

miss-islington commented Feb 7, 2023

Uh oh!

bedevere-bot commented Feb 17, 2023

Uh oh!

bedevere-bot commented Feb 17, 2023

Uh oh!

Uh oh!

bskinn commented Dec 15, 2022 •

edited by bedevere-bot

Loading

netlify bot commented Dec 15, 2022 •

edited

Loading

CAM-Gerlach left a comment •

edited

Loading