bpo-34831: Asyncio tutorial #9748

cjrh · 2018-10-07T10:25:35Z

https://bugs.python.org/issue34831

1st1 · 2018-10-07T18:15:50Z

cc @ambv -- Łukasz, would be great if you could take a look at this too and share some of your thoughts/experience.

1st1 · 2018-10-07T18:19:16Z

also @elprans please take a look.

Doc/library/asyncio-tutorial/asyncio-cookbook.rst

Doc/library/asyncio-tutorial/why-asyncio.rst

willingc

Thanks @cjrh. A few comments so far.

Doc/library/asyncio-tutorial/async-functions.rst

Doc/library/asyncio-tutorial/index.rst

tirkarthi · 2018-10-21T06:30:05Z

Docs failure could be due to recent logging related changes to fix Sphinx deprecation warnings in ee171a2

tirkarthi · 2018-10-21T07:14:27Z

Upstream issue : https://bugs.python.org/issue35036
PR : #10024

Running make suspicious with the fix locally for reference :

(venv) ➜  Doc git:(0e82bc95f2) ✗ make suspicious
mkdir -p build
Building NEWS from Misc/NEWS.d with blurb
PATH=./venv/bin:$PATH sphinx-build -b suspicious -d build/doctrees -D latex_elements.papersize=  . build/suspicious
Running Sphinx v1.8.1
loading pickled environment... done
loading ignore rules... done, 343 rules loaded
building [mo]: targets for 0 po files that are out of date
building [suspicious]: targets for 484 source files that are out of date
updating environment: [] 0 added, 11 changed, 0 removed
reading sources... [100%] whatsnew/changelog
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 30%] library/asyncio-tutorial/case-study-chat-server
/Users/karthikeyansingaravelan/stuff/python/cpython/Doc/venv/lib/python3.7/site-packages/sphinx/application.py:388: RemovedInSphinx20Warning: app.warning() is now deprecated. Use sphinx.util.logging instead.
  RemovedInSphinx20Warning)
writing output... [100%] whatsnew/index
WARNING: [library/asyncio-tutorial/case-study-chat-server:49] ":TODO" found in " (ref:TODO) to create a TCP server very"
build finished with problems, 1 warning.
make[1]: *** [build] Error 1
Suspicious check complete; look for any errors in the above output or in build/suspicious/suspicious.csv.  If all issues are false positives, append that file to tools/susp-ignored.csv.
make: *** [suspicious] Error 1

Doc/library/asyncio-tutorial/async-functions.rst

willingc · 2019-06-16T19:58:09Z

Hi @cjrh, Thanks for updating the PR. I will do my best to review it this week. Hope all is well in your world. ☀️

1st1 · 2019-06-16T20:11:43Z

Yeah, it's a huge improvement; I'll also try to find time to review this before 3.8 final.

JulienPalard · 2019-09-10T17:09:04Z

The unreadable build failure is due to Sphinx deprecating a function, I'm currently fixing it, but in the meantime here's the error you have to fix (or add to Doc/tools/susp-ignored.csv):

WARNING: [distutils/examples:267] "`" found in "This is the description of the ``foobar`` package."
WARNING: [library/asyncio-tutorial/running-async-functions:131] "`" found in "    task1 = func1()  // In Python: `task1 = create_task(func1())`"
WARNING: [library/asyncio-tutorial/running-async-functions:131] "`" found in "    task2 = func2()  // In Python: `task2 = create_task(func2())`"
WARNING: Found 1/355 unused rules:
distutils/examples,,`,This is the description of the ``foobar`` package.

JulienPalard · 2019-09-10T17:12:06Z

@cjrh You can now rebase on top of master, since e1786b5 the suspicious.py script is fixed.

cjrh · 2019-09-10T21:05:59Z

Thanks for the update, I'll rebase that soon.

1st1 · 2019-09-12T15:48:55Z

This is huge, thank you, @cjrh!

I'm a bit busy at the sprints right now, I'll review this soon.

asvetlov

Very impressive.
Please use a new stream API instead of legacy reader/writer.

asvetlov · 2019-09-12T20:15:52Z

Doc/library/asyncio-tutorial/async-functions.rst

+Async Functions, And Other Syntax Features
+==========================================
+
+Regular Python functions are created with the keyword ``def``,


Suggested change

Regular Python functions are created with the keyword ``def``,

Regular Python functions are created with the keyword :keyword:`def`,

Pushing :keyword: everywhere for building a link doesn't make sense but the first occurrence in a page can be a link, it's convenient maybe.

asvetlov · 2019-09-12T20:16:29Z

Doc/library/asyncio-tutorial/async-functions.rst

+    asyncio.run(f(1, 2))
+
+The first difference is that the function declaration is spelled
+``async def``. The second difference is that async functions cannot be


Suggested change

``async def``. The second difference is that async functions cannot be

:keyword:`async def`. The second difference is that async functions cannot be

asvetlov · 2019-09-12T20:17:00Z

Doc/library/asyncio-tutorial/async-functions.rst

+
+The first difference is that the function declaration is spelled
+``async def``. The second difference is that async functions cannot be
+executed by simply evaluating them. Instead, we use the ``run()`` function


Suggested change

executed by simply evaluating them. Instead, we use the ``run()`` function

executed by simply evaluating them. Instead, we use the :func:`~asyncio.run` function

asvetlov · 2019-09-12T20:17:16Z

Doc/library/asyncio-tutorial/async-functions.rst

+The first difference is that the function declaration is spelled
+``async def``. The second difference is that async functions cannot be
+executed by simply evaluating them. Instead, we use the ``run()`` function
+from the ``asyncio`` module.


Suggested change

from the ``asyncio`` module.

from the :mod:`asyncio` module.

asvetlov · 2019-09-12T20:17:47Z

Doc/library/asyncio-tutorial/async-functions.rst

+-------------------------
+
+The ``run`` function is only good for executing an async function
+from "synchronous" code; and this is usually only used to execute


Suggested change

from "synchronous" code; and this is usually only used to execute

from *synchronous* code; and this is usually only used to execute

asvetlov · 2019-09-12T20:30:53Z

Doc/library/asyncio-tutorial/asyncio-cookbook.rst

+Using A Queue To Move Data Between Long-Lived Tasks
+---------------------------------------------------
+
+TODO


asvetlov · 2019-09-12T20:34:54Z

Doc/library/asyncio-tutorial/asyncio-cookbook.rst

+Best Practices For Timeouts
+---------------------------
+
+- start with ``asyncio.wait_for()``


Suggested change

- start with ``asyncio.wait_for()``

- start with :func:`asyncio.wait_for()`

asvetlov · 2019-09-12T20:35:14Z

Doc/library/asyncio-tutorial/asyncio-cookbook.rst

+---------------------------
+
+- start with ``asyncio.wait_for()``
+- also look at ``asyncio.wait()``, and what to do if not all tasks


Suggested change

- also look at ``asyncio.wait()``, and what to do if not all tasks

- also look at :func:`asyncio.wait()`, and what to do if not all tasks

asvetlov · 2019-09-12T20:35:44Z

Doc/library/asyncio-tutorial/asyncio-cookbook.rst

+--------------------------
+
+- app shutdown
+- how to handle CancelledError and then close sockets


Suggested change

- how to handle CancelledError and then close sockets

- how to handle :exc:`~asyncio.CancelledError` and then close sockets

asvetlov · 2019-09-12T20:38:06Z

Doc/library/asyncio-tutorial/asyncio-cookbook.rst

+        ...
+
+    async def main():
+        server = await asyncio.start_server(


New API:

async with asyncio.StreamServer(client_connected_cb, 'localhost', 9011) as server: await server.serve_forever()

bedevere-bot · 2019-09-12T20:43:12Z

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.

asvetlov · 2019-09-13T10:55:56Z

I suggest splitting this combo PR into smaller sections.
For example, async_functions.rst is finished and almost ready for merging after a little polishing.
It makes a value in itself, we can process it fast.

kumaraditya303 · 2022-10-15T13:57:22Z

I am closing this as this will be split into smaller PRs as discussed in the issue. Thanks for the PR!

cjrh requested review from 1st1 and asvetlov as code owners October 7, 2018 10:25

the-knights-who-say-ni added the CLA signed label Oct 7, 2018

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Oct 7, 2018

cjrh force-pushed the bpo-34831-asyncio-tutorial branch from 9089420 to a7a9f25 Compare October 7, 2018 10:57

1st1 reviewed Oct 7, 2018

View reviewed changes

Doc/library/asyncio-tutorial/asyncio-cookbook.rst Show resolved Hide resolved

Doc/library/asyncio-tutorial/why-asyncio.rst Outdated Show resolved Hide resolved

cjrh force-pushed the bpo-34831-asyncio-tutorial branch from a7a9f25 to 4b47460 Compare October 12, 2018 14:34

willingc reviewed Oct 14, 2018

View reviewed changes

cjrh force-pushed the bpo-34831-asyncio-tutorial branch from 9f21e81 to 30d158d Compare October 21, 2018 04:15

cjrh force-pushed the bpo-34831-asyncio-tutorial branch from a6668dd to 7c95086 Compare November 4, 2018 05:52

tirkarthi reviewed Apr 12, 2019

View reviewed changes

Doc/library/asyncio-tutorial/async-functions.rst Outdated Show resolved Hide resolved

cjrh force-pushed the bpo-34831-asyncio-tutorial branch from 7c95086 to 8c2f3ff Compare June 15, 2019 03:30

cjrh added 8 commits September 11, 2019 22:45

Create basic structure of the asyncio tutorial

16d3b94

Begun work on the case study for the server

50a901e

Incorporate review comments from @willingc

dfede40

Refine language around threads and processes

a11e659

Incorporate message handling into server code

7e205d2

Add message receiving to server code.

7f2f149

Added skeleton suggestions for the cookbook section

61402e1

Further notes in the cookbook

550bdbf

cjrh added 16 commits September 11, 2019 22:45

Remove TODOs

be474f4

Write "Executing Async Functions"

c403101

Fix spurious backtick

69190b8

Make the case study (server) a little neater.

89f7ca2

Some refactoring and finishing off the server.

36fc743

Cleaned up the last bit of the chat server code sample.

d55d8fb

Further progress - got a CLI chat client working using prompt-toolkit.

34306f0

Include chat client code in the text.

0c82755

Fix typo

a774a98

Clarify switching behaviour

eedbc97

Add async generators and async context managers discussion.

a8a801d

Add some comparison with JavaScript async/await and asyncio.create_task

8e6dcfd

Fix "no good read" typo

0e5ed3f

Fix "do not required" typo

4714ed2

Modern -> modern

d71da67

Removing the GUI case study section

26cc634

cjrh force-pushed the bpo-34831-asyncio-tutorial branch from 576ef44 to 26cc634 Compare September 11, 2019 12:45

Remove problematic backticks inside a code-block

9530021

matrixise added the topic-asyncio label Sep 12, 2019

JulienPalard requested a review from 1st1 September 12, 2019 14:16

asvetlov requested changes Sep 12, 2019

View reviewed changes

bedevere-bot added awaiting changes and removed awaiting review labels Sep 12, 2019

cjrh mannequin mentioned this pull request Apr 17, 2022

Asyncio Tutorial #79012

Open

ezio-melotti removed the CLA signed label Jul 13, 2022

kumaraditya303 closed this Oct 15, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-34831: Asyncio tutorial #9748

bpo-34831: Asyncio tutorial #9748

cjrh commented Oct 7, 2018 •

edited by bedevere-bot

Loading

1st1 commented Oct 7, 2018

1st1 commented Oct 7, 2018

willingc left a comment

tirkarthi commented Oct 21, 2018

tirkarthi commented Oct 21, 2018

willingc commented Jun 16, 2019

1st1 commented Jun 16, 2019

JulienPalard commented Sep 10, 2019

JulienPalard commented Sep 10, 2019

cjrh commented Sep 10, 2019

1st1 commented Sep 12, 2019

asvetlov left a comment

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

asvetlov Sep 12, 2019

bedevere-bot commented Sep 12, 2019

asvetlov commented Sep 13, 2019

kumaraditya303 commented Oct 15, 2022

	Regular Python functions are created with the keyword ``def``,
	Regular Python functions are created with the keyword :keyword:`def`,

	``async def``. The second difference is that async functions cannot be
	:keyword:`async def`. The second difference is that async functions cannot be

	executed by simply evaluating them. Instead, we use the ``run()`` function
	executed by simply evaluating them. Instead, we use the :func:`~asyncio.run` function

	from "synchronous" code; and this is usually only used to execute
	from synchronous code; and this is usually only used to execute

	- start with ``asyncio.wait_for()``
	- start with :func:`asyncio.wait_for()`

	- also look at ``asyncio.wait()``, and what to do if not all tasks
	- also look at :func:`asyncio.wait()`, and what to do if not all tasks

	- how to handle CancelledError and then close sockets
	- how to handle :exc:`~asyncio.CancelledError` and then close sockets

bpo-34831: Asyncio tutorial #9748

bpo-34831: Asyncio tutorial #9748

Conversation

cjrh commented Oct 7, 2018 • edited by bedevere-bot Loading

1st1 commented Oct 7, 2018

1st1 commented Oct 7, 2018

willingc left a comment

Choose a reason for hiding this comment

tirkarthi commented Oct 21, 2018

tirkarthi commented Oct 21, 2018

willingc commented Jun 16, 2019

1st1 commented Jun 16, 2019

JulienPalard commented Sep 10, 2019

JulienPalard commented Sep 10, 2019

cjrh commented Sep 10, 2019

1st1 commented Sep 12, 2019

asvetlov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bedevere-bot commented Sep 12, 2019

asvetlov commented Sep 13, 2019

kumaraditya303 commented Oct 15, 2022

cjrh commented Oct 7, 2018 •

edited by bedevere-bot

Loading