Skip to content

bpo-36802: Drop awrite()/aclose(), support await write() and await close() instead #13099

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
asvetlov merged 10 commits into from
May 9, 2019
Merged

bpo-36802: Drop awrite()/aclose(), support await write() and await close() instead #13099

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
74dafce
Make close and write optionally async
asvetlov May 5, 2019
8e25ae5
Fix waiting in StreamWriter.drain for closing SSL transport
asvetlov May 5, 2019
9b0c34e
Merge branch 'master' into drop-awrite
asvetlov May 5, 2019
c50084a
Support await by stream.write(), stream.writelines() and stream.close…
asvetlov May 5, 2019
b6e5502
Add proto._get_close_waiter(stream) to get closing future for corresp…
asvetlov May 5, 2019
a80349e
Merge branch 'streams-wait-ssl-shutdown' into drop-awrite
asvetlov May 5, 2019
e2fed9f
Fix subprocess tests
asvetlov May 5, 2019
d3e4685
Update documentation for changed methods
asvetlov May 7, 2019
6255d2b
Add a comment to emphasize fast path for stream draining
asvetlov May 7, 2019
b5ae9d7
Merge branch 'master' into drop-awrite
asvetlov May 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update documentation for changed methods
  • Loading branch information
@asvetlov
asvetlov committed May 7, 2019
commit d3e46858bb239a653eabd1176263e3e7f963e38a
60 changes: 41 additions & 19 deletions Doc/library/asyncio-stream.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,43 +228,65 @@ StreamWriter

.. method:: write(data)

Write *data* to the stream.
The method attempts to write the *data* to the underlying socket immediately.
If that fails, the data is queued in an internal write buffer until it can be
sent.

If the method is called using ``await stream.write(data)`` syntax it
respects flow control, execution is paused if the write buffer reaches the high
watermark *(recommended API)*.
Starting with Python 3.8, it is possible to directly await on the `write()`
method::

If the method is called using *sync* ``stream.write(data)`` form it *is not* a
subject to flow control. Such call should
be followed by :meth:`drain`.
await stream.write(data)

The ``await`` pauses the current coroutine until the data is written to the
socket.

Below is an equivalent code that works with Python <= 3.7::

stream.write(data)
await stream.drain()

.. versionchanged:: 3.8
Support ``await stream.write(...)`` syntax.

.. method:: writelines(data)

Write a list (or any iterable) of bytes to the stream.
The method writes a list (or any iterable) of bytes to the underlying socket
immediately.
If that fails, the data is queued in an internal write buffer until it can be
sent.

Starting with Python 3.8, it is possible to directly await on the `write()`
method::

await stream.writelines(lines)

If the method is called using ``await stream.writelines(lines)`` syntax it
respects flow control, execution is paused if the write buffer reaches the high
watermark *(recommended API)*.
The ``await`` pauses the current coroutine until the data is written to the
socket.

If the method is called using *sync* ``stream.writelines(lines)`` form it *is not*
subject to flow control. Such calls should be followed by :meth:`drain`.
Below is an equivalent code that works with Python <= 3.7::

stream.writelines(lines)
await stream.drain()

.. versionchanged:: 3.8
Support ``await stream.writelines()`` syntax.

.. method:: close()

Close the stream.
The method closes the stream and the underlying socket.

Starting with Python 3.8, it is possible to directly await on the `close()`
method::

await stream.close()

The ``await`` pauses the current coroutine until the stream and the underlying
socket are closed (and SSL shutdown is performed for a secure connection).

If the method is called using ``await stream.close()`` syntax it waits until all
closing actions are complete, e.g. SSL shutdown for secure sockets *(recommended
API)*.
Below is an equivalent code that works with Python <= 3.7::

If the method is called using *sync* ``stream.close()`` form it *does not* wait
for actual socket closing. The call should be followed by :meth:`wait_closed`.
stream.close()
await stream.wait_closed()

.. versionchanged:: 3.8
Support ``await stream.close()`` syntax.
Expand Down