From 7ed4629253fd7b472a78e7cefc5001619b2e8255 Mon Sep 17 00:00:00 2001 From: Xtreak Date: Tue, 25 Jun 2019 12:12:48 +0530 Subject: [PATCH 1/9] Document Stream and add docstrings --- Doc/library/asyncio-stream.rst | 172 ++++++++++++++++++++++++++++++++- Lib/asyncio/streams.py | 18 ++++ 2 files changed, 188 insertions(+), 2 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index dfe520de56bf04..04216dc3718c80 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -46,7 +46,6 @@ and work with streams: Connect to TCP socket on *host* : *port* address and return a :class:`Stream` object of mode :attr:`StreamMode.READWRITE`. - *limit* determines the buffer size limit used by the returned :class:`Stream` instance. By default the *limit* is set to 64 KiB. @@ -367,13 +366,182 @@ Stream Represents a Stream object that provides APIs to read and write data to the IO stream . It includes the API provided by :class:`StreamReader` - and :class:`StreamWriter`. + and :class:`StreamWriter`. It can also be used as :term:`asynchronous iterator` + where :meth:`readline` is used. It raises :exc:`StopAsyncIteration` when + :meth:`readline` returns empty data. Do not instantiate *Stream* objects directly; use API like :func:`connect` and :class:`StreamServer` instead. .. versionadded:: 3.8 + .. attribute:: mode + + Returns the mode of the stream which is a :class:`StreamMode`. + + .. method:: set_exception(exc) + + Sets the exception to be raised when :meth:`read`, :meth:`readexactly` and + :meth:`readuntil` are called. + + .. coroutinemethod:: abort() + + Aborts the :ref:`Transport ` instance used by the Stream. + + .. coroutinemethod:: sendfile(file, offset=0, count=None, *, fallback=True) + + Calls :meth:`Stream.drain()` and rest of the arguments are passed directly to + :meth:`loop.sendfile`. + + .. coroutinemethod:: start_tls(sslcontext, *, server_hostname=None, \ + ssl_handshake_timeout=None) + + Calls :meth:`Stream.drain()` and rest of the arguments are passed directly to + :meth:`loop.start_tls`. + + .. coroutinemethod:: read(n=-1) + + Read up to *n* bytes. If *n* is not provided, or set to ``-1``, + read until EOF and return all read bytes. + + If EOF was received and the internal buffer is empty, + return an empty ``bytes`` object. + + .. coroutinemethod:: readline() + + Read one line, where "line" is a sequence of bytes + ending with ``\n``. + + If EOF is received and ``\n`` was not found, the method + returns partially read data. + + If EOF is received and the internal buffer is empty, + return an empty ``bytes`` object. + + .. coroutinemethod:: readexactly(n) + + Read exactly *n* bytes. + + Raise an :exc:`IncompleteReadError` if EOF is reached before *n* + can be read. Use the :attr:`IncompleteReadError.partial` + attribute to get the partially read data. + + .. coroutinemethod:: readuntil(separator=b'\\n') + + Read data from the stream until *separator* is found. + + On success, the data and separator will be removed from the + internal buffer (consumed). Returned data will include the + separator at the end. + + If the amount of data read exceeds the configured stream limit, a + :exc:`LimitOverrunError` exception is raised, and the data + is left in the internal buffer and can be read again. + + If EOF is reached before the complete separator is found, + an :exc:`IncompleteReadError` exception is raised, and the internal + buffer is reset. The :attr:`IncompleteReadError.partial` attribute + may contain a portion of the separator. + + .. method:: at_eof() + + Return ``True`` if the buffer is empty and :meth:`feed_eof` + was called. + + .. method:: feed_data(data) + + Adds ``data`` to the write buffer. It raises an :exc:`AssertionError` when + it was called after :meth:`feed_eof`. + + .. method:: write(data) + + 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. + + It is possible to directly await on the `write()` method:: + + await stream.write(data) + + The ``await`` pauses the current coroutine until the data is written to the + socket. + + .. method:: writelines(data) + + 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. + + It is possible to directly await on the `write()` method:: + + await stream.writelines(lines) + + The ``await`` pauses the current coroutine until the data is written to the + socket. + + .. method:: close() + + The method closes the stream and the underlying socket. + + 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). + + Below is an equivalent code that works with Python <= 3.7:: + + stream.close() + await stream.wait_closed() + + .. method:: can_write_eof() + + Return *True* if the underlying transport supports + the :meth:`write_eof` method, *False* otherwise. + + .. method:: write_eof() + + Close the write end of the stream after the buffered write + data is flushed. + + .. attribute:: transport + + Return the underlying asyncio transport. + + .. method:: get_extra_info(name, default=None) + + Access optional transport information; see + :meth:`BaseTransport.get_extra_info` for details. + + .. coroutinemethod:: drain() + + Wait until it is appropriate to resume writing to the stream. + Example:: + + stream.write(data) + await stream.drain() + + This is a flow control method that interacts with the underlying + IO write buffer. When the size of the buffer reaches + the high watermark, *drain()* blocks until the size of the + buffer is drained down to the low watermark and writing can + be resumed. When there is nothing to wait for, the :meth:`drain` + returns immediately. + + .. method:: is_closing() + + Return ``True`` if the stream is closed or in the process of + being closed. + + .. coroutinemethod:: wait_closed() + + Wait until the stream is closed. + + Should be called after :meth:`close` to wait until the underlying + connection is closed. + StreamMode ========== diff --git a/Lib/asyncio/streams.py b/Lib/asyncio/streams.py index 204eaf7394c5bb..2fbdda444d0cbb 100644 --- a/Lib/asyncio/streams.py +++ b/Lib/asyncio/streams.py @@ -70,6 +70,14 @@ def connect(host=None, port=None, *, server_hostname=None, ssl_handshake_timeout=None, happy_eyeballs_delay=None, interleave=None): + """Connect to TCP socket on *host* : *port* address and return a `Stream` + object of mode StreamMode.READWRITE. + + *limit* determines the buffer size limit used by the returned `Stream` + instance. By default the *limit* is set to 64 KiB. + + The rest of the arguments are passed directly to `loop.create_connection()`. + """ # Design note: # Don't use decorator approach but exilicit non-async # function to fail fast and explicitly @@ -108,6 +116,11 @@ async def _connect(host, port, def connect_read_pipe(pipe, *, limit=_DEFAULT_LIMIT): + """Takes a file-like object *pipe* to return a Stream object of the mode + StreamMode.READ that has similar API of StreamReader. It can also be used + as an async context manager. + """ + # Design note: # Don't use decorator approach but explicit non-async # function to fail fast and explicitly @@ -129,6 +142,11 @@ async def _connect_read_pipe(pipe, limit): def connect_write_pipe(pipe, *, limit=_DEFAULT_LIMIT): + """Takes a file-like object *pipe* to return a Stream object of the mode + StreamMode.WRITE that has similar API of StreamWriter. It can also be used + as an async context manager. + """ + # Design note: # Don't use decorator approach but explicit non-async # function to fail fast and explicitly From e2a64adcd6b5703e727e9720b0007303e5b2c500 Mon Sep 17 00:00:00 2001 From: Xtreak Date: Tue, 25 Jun 2019 15:31:22 +0530 Subject: [PATCH 2/9] Remove 3.7 example and group the functions --- Doc/library/asyncio-stream.rst | 57 ++++++++++++++++------------------ 1 file changed, 26 insertions(+), 31 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 04216dc3718c80..5a8da23354eb0b 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -377,7 +377,7 @@ Stream .. attribute:: mode - Returns the mode of the stream which is a :class:`StreamMode`. + Returns the mode of the stream which is a :class:`StreamMode` value. .. method:: set_exception(exc) @@ -388,6 +388,21 @@ Stream Aborts the :ref:`Transport ` instance used by the Stream. + .. coroutinemethod:: drain() + + Wait until it is appropriate to resume writing to the stream. + Example:: + + stream.write(data) + await stream.drain() + + This is a flow control method that interacts with the underlying + IO write buffer. When the size of the buffer reaches + the high watermark, *drain()* blocks until the size of the + buffer is drained down to the low watermark and writing can + be resumed. When there is nothing to wait for, the :meth:`drain` + returns immediately. + .. coroutinemethod:: sendfile(file, offset=0, count=None, *, fallback=True) Calls :meth:`Stream.drain()` and rest of the arguments are passed directly to @@ -443,16 +458,6 @@ Stream buffer is reset. The :attr:`IncompleteReadError.partial` attribute may contain a portion of the separator. - .. method:: at_eof() - - Return ``True`` if the buffer is empty and :meth:`feed_eof` - was called. - - .. method:: feed_data(data) - - Adds ``data`` to the write buffer. It raises an :exc:`AssertionError` when - it was called after :meth:`feed_eof`. - .. method:: write(data) The method attempts to write the *data* to the underlying socket immediately. @@ -491,11 +496,6 @@ Stream The ``await`` pauses the current coroutine until the stream and the underlying socket are closed (and SSL shutdown is performed for a secure connection). - Below is an equivalent code that works with Python <= 3.7:: - - stream.close() - await stream.wait_closed() - .. method:: can_write_eof() Return *True* if the underlying transport supports @@ -506,6 +506,16 @@ Stream Close the write end of the stream after the buffered write data is flushed. + .. method:: at_eof() + + Return ``True`` if the buffer is empty and :meth:`feed_eof` + was called. + + .. method:: feed_data(data) + + Adds ``data`` to the write buffer. It raises an :exc:`AssertionError` when + it was called after :meth:`feed_eof`. + .. attribute:: transport Return the underlying asyncio transport. @@ -515,21 +525,6 @@ Stream Access optional transport information; see :meth:`BaseTransport.get_extra_info` for details. - .. coroutinemethod:: drain() - - Wait until it is appropriate to resume writing to the stream. - Example:: - - stream.write(data) - await stream.drain() - - This is a flow control method that interacts with the underlying - IO write buffer. When the size of the buffer reaches - the high watermark, *drain()* blocks until the size of the - buffer is drained down to the low watermark and writing can - be resumed. When there is nothing to wait for, the :meth:`drain` - returns immediately. - .. method:: is_closing() Return ``True`` if the stream is closed or in the process of From 19798d504348dabc2a650cd0fb21a1aaf38a9245 Mon Sep 17 00:00:00 2001 From: Xtreak Date: Mon, 1 Jul 2019 16:20:25 +0530 Subject: [PATCH 3/9] Fix tabs error --- Doc/library/asyncio-stream.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 5a8da23354eb0b..f1fbd69580fce2 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -409,7 +409,7 @@ Stream :meth:`loop.sendfile`. .. coroutinemethod:: start_tls(sslcontext, *, server_hostname=None, \ - ssl_handshake_timeout=None) + ssl_handshake_timeout=None) Calls :meth:`Stream.drain()` and rest of the arguments are passed directly to :meth:`loop.start_tls`. From 8ac511618af202d26f1224de046932f8df1241cd Mon Sep 17 00:00:00 2001 From: Xtreak Date: Tue, 10 Sep 2019 12:31:51 +0100 Subject: [PATCH 4/9] Add methods to API index and remove deprecated methods. --- Doc/library/asyncio-api-index.rst | 25 +++++++++++++++++++++++ Doc/library/asyncio-stream.rst | 33 +++++++++++-------------------- Lib/asyncio/streams.py | 11 +++++++---- 3 files changed, 43 insertions(+), 26 deletions(-) diff --git a/Doc/library/asyncio-api-index.rst b/Doc/library/asyncio-api-index.rst index d5b5659abc65e2..e368e244ba96c2 100644 --- a/Doc/library/asyncio-api-index.rst +++ b/Doc/library/asyncio-api-index.rst @@ -132,18 +132,43 @@ High-level APIs to work with network IO. :widths: 50 50 :class: full-width-table + * - ``await`` :func:`connect` + - Establish a TCP connection to send and receive data. + * - ``await`` :func:`open_connection` - Establish a TCP connection. + * - ``await`` :func:`connect_unix` + - Establish a Unix socket connection to send and receive data. + * - ``await`` :func:`open_unix_connection` - Establish a Unix socket connection. + * - :class:`StreamServer` + - Start a TCP server. + * - ``await`` :func:`start_server` - Start a TCP server. + * - :class:`UnixStreamServer` + - Start a Unix socket server. + * - ``await`` :func:`start_unix_server` - Start a Unix socket server. + * - :func:`connect_read_pipe` + - Establish a connection to :term:`file-like object ` *pipe* + to receive data. + + * - :func:`connect_write_pipe` + - Establish a connection to :term:`file-like object ` *pipe* + to send data. + + * - :class:`Stream` + - High-level async/await object to send and receive network data. + It includes the API provided by :class:`StreamReader` + and :class:`StreamWriter`. + * - :class:`StreamReader` - High-level async/await object to receive network data. diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index f1fbd69580fce2..e51225e7b7f0a5 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -377,12 +377,12 @@ Stream .. attribute:: mode - Returns the mode of the stream which is a :class:`StreamMode` value. + Returns the mode of the stream which is a :class:`StreamMode` value. It could + be one of the below : - .. method:: set_exception(exc) - - Sets the exception to be raised when :meth:`read`, :meth:`readexactly` and - :meth:`readuntil` are called. + * :attr:`StreamMode.READ` - Connection can receive data. + * :attr:`StreamMode.WRITE` - Connection can send data. + * :attr:`StreamMode.READWRITE` - Connection can send and receive data. .. coroutinemethod:: abort() @@ -405,14 +405,14 @@ Stream .. coroutinemethod:: sendfile(file, offset=0, count=None, *, fallback=True) - Calls :meth:`Stream.drain()` and rest of the arguments are passed directly to - :meth:`loop.sendfile`. + Calls :meth:`Stream.drain()` to write to the connection and uses :meth:`loop.sendfile` + to send *file* over *transport*. .. coroutinemethod:: start_tls(sslcontext, *, server_hostname=None, \ ssl_handshake_timeout=None) - Calls :meth:`Stream.drain()` and rest of the arguments are passed directly to - :meth:`loop.start_tls`. + Calls :meth:`Stream.drain()` to write to the connection and uses :meth:`loop.start_tls` + to upgrade the existing transport-based connection to TLS. .. coroutinemethod:: read(n=-1) @@ -508,17 +508,7 @@ Stream .. method:: at_eof() - Return ``True`` if the buffer is empty and :meth:`feed_eof` - was called. - - .. method:: feed_data(data) - - Adds ``data`` to the write buffer. It raises an :exc:`AssertionError` when - it was called after :meth:`feed_eof`. - - .. attribute:: transport - - Return the underlying asyncio transport. + Return ``True`` if the buffer is empty. .. method:: get_extra_info(name, default=None) @@ -622,8 +612,7 @@ StreamReader .. method:: at_eof() - Return ``True`` if the buffer is empty and :meth:`feed_eof` - was called. + Return ``True`` if the buffer is empty. StreamWriter diff --git a/Lib/asyncio/streams.py b/Lib/asyncio/streams.py index 2fbdda444d0cbb..b7ef9eb7c647f8 100644 --- a/Lib/asyncio/streams.py +++ b/Lib/asyncio/streams.py @@ -70,8 +70,7 @@ def connect(host=None, port=None, *, server_hostname=None, ssl_handshake_timeout=None, happy_eyeballs_delay=None, interleave=None): - """Connect to TCP socket on *host* : *port* address and return a `Stream` - object of mode StreamMode.READWRITE. + """Connect to TCP socket on *host* : *port* address to send and receive data. *limit* determines the buffer size limit used by the returned `Stream` instance. By default the *limit* is set to 64 KiB. @@ -116,7 +115,9 @@ async def _connect(host, port, def connect_read_pipe(pipe, *, limit=_DEFAULT_LIMIT): - """Takes a file-like object *pipe* to return a Stream object of the mode + """Establish a connection to a file-like object *pipe* to receive data. + + Takes a file-like object *pipe* to return a Stream object of the mode StreamMode.READ that has similar API of StreamReader. It can also be used as an async context manager. """ @@ -142,7 +143,9 @@ async def _connect_read_pipe(pipe, limit): def connect_write_pipe(pipe, *, limit=_DEFAULT_LIMIT): - """Takes a file-like object *pipe* to return a Stream object of the mode + """Establish a connection to a file-like object *pipe* to send data. + + Takes a file-like object *pipe* to return a Stream object of the mode StreamMode.WRITE that has similar API of StreamWriter. It can also be used as an async context manager. """ From 479a8605b90540cee548ed705b6a393f43d474c3 Mon Sep 17 00:00:00 2001 From: Xtreak Date: Tue, 10 Sep 2019 15:57:25 +0100 Subject: [PATCH 5/9] Add deprecations to index. Reword few sentences. --- Doc/library/asyncio-api-index.rst | 17 ++++++++--------- Doc/library/asyncio-stream.rst | 4 ++-- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/Doc/library/asyncio-api-index.rst b/Doc/library/asyncio-api-index.rst index e368e244ba96c2..716cf09dc99eae 100644 --- a/Doc/library/asyncio-api-index.rst +++ b/Doc/library/asyncio-api-index.rst @@ -136,25 +136,25 @@ High-level APIs to work with network IO. - Establish a TCP connection to send and receive data. * - ``await`` :func:`open_connection` - - Establish a TCP connection. + - Establish a TCP connection. (Deprecated in favor of :func:`connect`) * - ``await`` :func:`connect_unix` - Establish a Unix socket connection to send and receive data. * - ``await`` :func:`open_unix_connection` - - Establish a Unix socket connection. + - Establish a Unix socket connection. (Deprecated in favor of :func:`connect_unix`) * - :class:`StreamServer` - Start a TCP server. * - ``await`` :func:`start_server` - - Start a TCP server. + - Start a TCP server. (Deprecated in favor of :class:`StreamServer`) * - :class:`UnixStreamServer` - Start a Unix socket server. * - ``await`` :func:`start_unix_server` - - Start a Unix socket server. + - Start a Unix socket server. (Deprecated in favor of :class:`UnixStreamServer`) * - :func:`connect_read_pipe` - Establish a connection to :term:`file-like object ` *pipe* @@ -165,15 +165,14 @@ High-level APIs to work with network IO. to send data. * - :class:`Stream` - - High-level async/await object to send and receive network data. - It includes the API provided by :class:`StreamReader` - and :class:`StreamWriter`. + - Stream is a single object combining APIs of :class:`StreamReader` and + :class:`StreamWriter`. * - :class:`StreamReader` - - High-level async/await object to receive network data. + - High-level async/await object to receive network data. (Deprecated in favor of :class:`Stream`) * - :class:`StreamWriter` - - High-level async/await object to send network data. + - High-level async/await object to send network data. (Deprecated in favor of :class:`Stream`) .. rubric:: Examples diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index e51225e7b7f0a5..e48ef1073b5d3c 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -378,7 +378,7 @@ Stream .. attribute:: mode Returns the mode of the stream which is a :class:`StreamMode` value. It could - be one of the below : + be one of the below: * :attr:`StreamMode.READ` - Connection can receive data. * :attr:`StreamMode.WRITE` - Connection can send data. @@ -386,7 +386,7 @@ Stream .. coroutinemethod:: abort() - Aborts the :ref:`Transport ` instance used by the Stream. + Aborts the connection immediately, without waiting for the send buffer to drain. .. coroutinemethod:: drain() From df72ef48a313ef243528359698ce5a4994d59359 Mon Sep 17 00:00:00 2001 From: Xtreak Date: Wed, 11 Sep 2019 11:12:42 +0100 Subject: [PATCH 6/9] Remove reference to stream.drain. Add a note on stream.write as a method and a coroutine. --- Doc/library/asyncio-stream.rst | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index e48ef1073b5d3c..fc253ac0f81309 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -405,14 +405,16 @@ Stream .. coroutinemethod:: sendfile(file, offset=0, count=None, *, fallback=True) - Calls :meth:`Stream.drain()` to write to the connection and uses :meth:`loop.sendfile` - to send *file* over *transport*. + Sends a *file* over the stream using an optimized syscall if available. + + For other parameters meaning please see :meth:`AbstractEventloop.sendfile`. .. coroutinemethod:: start_tls(sslcontext, *, server_hostname=None, \ ssl_handshake_timeout=None) - Calls :meth:`Stream.drain()` to write to the connection and uses :meth:`loop.start_tls` - to upgrade the existing transport-based connection to TLS. + Upgrades the existing transport-based connection to TLS. + + For other parameters meaning please see :meth:`AbstractEventloop.start_tls`. .. coroutinemethod:: read(n=-1) @@ -458,18 +460,25 @@ Stream buffer is reset. The :attr:`IncompleteReadError.partial` attribute may contain a portion of the separator. + .. coroutinemethod:: write(data) + + Write *data* to the underlying socket; wait until the data is sent, e.g.:: + + await stream.write(data) + .. method:: write(data) 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. + sent. :meth:`drain` can be used to flush the underlying buffer once writing is + available:: - It is possible to directly await on the `write()` method:: + stream.write(data) + await stream.drain() - await stream.write(data) + It is recommended to directly await on the `write()` method instead:: - The ``await`` pauses the current coroutine until the data is written to the - socket. + await stream.write(data) .. method:: writelines(data) From 99fefef655f466a56c9def6faa477061a897156c Mon Sep 17 00:00:00 2001 From: Xtreak Date: Fri, 13 Sep 2019 10:23:29 +0100 Subject: [PATCH 7/9] Add deprecated notes to recommend await stream.write --- Doc/library/asyncio-stream.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index fc253ac0f81309..cc9e7b712ff05a 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -403,6 +403,12 @@ Stream be resumed. When there is nothing to wait for, the :meth:`drain` returns immediately. + .. deprecated:: 3.8 + + It is recommended to directly await on the `write()` method instead:: + + await stream.write(data) + .. coroutinemethod:: sendfile(file, offset=0, count=None, *, fallback=True) Sends a *file* over the stream using an optimized syscall if available. @@ -476,9 +482,11 @@ Stream stream.write(data) await stream.drain() + .. deprecated:: 3.8 + It is recommended to directly await on the `write()` method instead:: - await stream.write(data) + await stream.write(data) .. method:: writelines(data) From c191de6f8456585d9a75f220f12c6cfbc78c1d78 Mon Sep 17 00:00:00 2001 From: Xtreak Date: Fri, 13 Sep 2019 10:27:38 +0100 Subject: [PATCH 8/9] Fix write to writelines. --- Doc/library/asyncio-stream.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index cc9e7b712ff05a..90f2a42376a137 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -495,7 +495,7 @@ Stream If that fails, the data is queued in an internal write buffer until it can be sent. - It is possible to directly await on the `write()` method:: + It is possible to directly await on the `writelines()` method:: await stream.writelines(lines) @@ -673,7 +673,7 @@ StreamWriter 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()` + Starting with Python 3.8, it is possible to directly await on the `writelines()` method:: await stream.writelines(lines) From 623afb54660ede777a24f02060d53dbd41fad229 Mon Sep 17 00:00:00 2001 From: Xtreak Date: Fri, 13 Sep 2019 11:32:47 +0100 Subject: [PATCH 9/9] Sort the methods by alphabet. --- Doc/library/asyncio-stream.rst | 108 ++++++++++++++++----------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 90f2a42376a137..feebd227eb8cad 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -388,6 +388,26 @@ Stream Aborts the connection immediately, without waiting for the send buffer to drain. + .. method:: at_eof() + + Return ``True`` if the buffer is empty. + + .. method:: can_write_eof() + + Return *True* if the underlying transport supports + the :meth:`write_eof` method, *False* otherwise. + + .. method:: close() + + The method closes the stream and the underlying socket. + + 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). + .. coroutinemethod:: drain() Wait until it is appropriate to resume writing to the stream. @@ -409,18 +429,15 @@ Stream await stream.write(data) - .. coroutinemethod:: sendfile(file, offset=0, count=None, *, fallback=True) - - Sends a *file* over the stream using an optimized syscall if available. - - For other parameters meaning please see :meth:`AbstractEventloop.sendfile`. + .. method:: get_extra_info(name, default=None) - .. coroutinemethod:: start_tls(sslcontext, *, server_hostname=None, \ - ssl_handshake_timeout=None) + Access optional transport information; see + :meth:`BaseTransport.get_extra_info` for details. - Upgrades the existing transport-based connection to TLS. + .. method:: is_closing() - For other parameters meaning please see :meth:`AbstractEventloop.start_tls`. + Return ``True`` if the stream is closed or in the process of + being closed. .. coroutinemethod:: read(n=-1) @@ -430,6 +447,14 @@ Stream If EOF was received and the internal buffer is empty, return an empty ``bytes`` object. + .. coroutinemethod:: readexactly(n) + + Read exactly *n* bytes. + + Raise an :exc:`IncompleteReadError` if EOF is reached before *n* + can be read. Use the :attr:`IncompleteReadError.partial` + attribute to get the partially read data. + .. coroutinemethod:: readline() Read one line, where "line" is a sequence of bytes @@ -441,14 +466,6 @@ Stream If EOF is received and the internal buffer is empty, return an empty ``bytes`` object. - .. coroutinemethod:: readexactly(n) - - Read exactly *n* bytes. - - Raise an :exc:`IncompleteReadError` if EOF is reached before *n* - can be read. Use the :attr:`IncompleteReadError.partial` - attribute to get the partially read data. - .. coroutinemethod:: readuntil(separator=b'\\n') Read data from the stream until *separator* is found. @@ -466,6 +483,26 @@ Stream buffer is reset. The :attr:`IncompleteReadError.partial` attribute may contain a portion of the separator. + .. coroutinemethod:: sendfile(file, offset=0, count=None, *, fallback=True) + + Sends a *file* over the stream using an optimized syscall if available. + + For other parameters meaning please see :meth:`AbstractEventloop.sendfile`. + + .. coroutinemethod:: start_tls(sslcontext, *, server_hostname=None, \ + ssl_handshake_timeout=None) + + Upgrades the existing transport-based connection to TLS. + + For other parameters meaning please see :meth:`AbstractEventloop.start_tls`. + + .. coroutinemethod:: wait_closed() + + Wait until the stream is closed. + + Should be called after :meth:`close` to wait until the underlying + connection is closed. + .. coroutinemethod:: write(data) Write *data* to the underlying socket; wait until the data is sent, e.g.:: @@ -502,48 +539,11 @@ Stream The ``await`` pauses the current coroutine until the data is written to the socket. - .. method:: close() - - The method closes the stream and the underlying socket. - - 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). - - .. method:: can_write_eof() - - Return *True* if the underlying transport supports - the :meth:`write_eof` method, *False* otherwise. - .. method:: write_eof() Close the write end of the stream after the buffered write data is flushed. - .. method:: at_eof() - - Return ``True`` if the buffer is empty. - - .. method:: get_extra_info(name, default=None) - - Access optional transport information; see - :meth:`BaseTransport.get_extra_info` for details. - - .. method:: is_closing() - - Return ``True`` if the stream is closed or in the process of - being closed. - - .. coroutinemethod:: wait_closed() - - Wait until the stream is closed. - - Should be called after :meth:`close` to wait until the underlying - connection is closed. - StreamMode ==========