asyncio Streams wait_closed

[OscilloPope]

Documentation

https://docs.python.org/3/library/asyncio-stream.html - assuming that await stream.wait_closed() should be called after all uses of .close() - which both the close() and wait_closed() methods both heavily suggest should be the case - then all examples on this page should also demonstrate this practice. At present only the first one (at the top) does: the examples at the bottom don't use wait_closed().

The documentation for wait_closed also doesn't really say why it should always be used beyond "to wait until the underlying connection is closed" which doesn't really explain anything.

Linked PRs

• gh-100920: Update documentation for asyncio wait_close #101514
• [3.11] gh-100920: Update documentation for asyncio.StreamWriter.wait_closed (GH-101514) #101532
• [3.10] gh-100920: Update documentation for asyncio.StreamWriter.wait_closed (GH-101514) #101533

[gvanrossum]

Thanks for your report!

Looking through the source code, it's not mandatory to call stream.wait_closed() after stream.close(). However, you should call it if you want to ensure that all the data has been flushed before e.g. exiting the program. Looking at the code it is also possible for stream.wait_close() to raise an exception, when the connection was closed with an error before all the data is flushed.

Maybe you'd like to try your hand at submitting a PR with an update to the docs, to clarify this?

Hello!
New contributor here. Could I take this issue?

[gvanrossum]

Sure. I hope you’ve studied the dev guide?

Yes. I am unable to build though.
PCbuild\build.bat -c Debug is raising an error. I have forked, cloned, updated my local repo and pushed it back to my origin. Now should I create a pull request?

[gvanrossum]

Can you ask for help on discuss.python.org?

All right.

[VietThan]

I would like to work on this if no one is.

[gvanrossum]

We haven't heard back from @ghost so feel free to submit a PR.