bpo-36889: Document Stream class and add docstrings (GH-14488)
* This just copies the docs from `StreamWriter` and `StreamReader`. * Add docstring for asyncio functions. https://bugs.python.org/issue36889 Automerge-Triggered-By: @asvetlov
This commit is contained in:
Xtreak
Miss Islington (bot)
parent
6a517c6749
commit
d31b31516c
|
|
@ -132,23 +132,47 @@ 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.
|
||||
- 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`)
|
||||
|
||||
* - ``await`` :func:`start_server`
|
||||
* - :class:`StreamServer`
|
||||
- Start a TCP server.
|
||||
|
||||
* - ``await`` :func:`start_unix_server`
|
||||
* - ``await`` :func:`start_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. (Deprecated in favor of :class:`UnixStreamServer`)
|
||||
|
||||
* - :func:`connect_read_pipe`
|
||||
- Establish a connection to :term:`file-like object <file object>` *pipe*
|
||||
to receive data.
|
||||
|
||||
* - :func:`connect_write_pipe`
|
||||
- Establish a connection to :term:`file-like object <file object>` *pipe*
|
||||
to send data.
|
||||
|
||||
* - :class:`Stream`
|
||||
- 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
|
||||
|
|
|
|||
|
|
@ -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,184 @@ 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` value. It could
|
||||
be one of the below:
|
||||
|
||||
* :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()
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
.. deprecated:: 3.8
|
||||
|
||||
It is recommended to directly await on the `write()` method instead::
|
||||
|
||||
await stream.write(data)
|
||||
|
||||
.. 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:: 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:: 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
|
||||
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:: 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.
|
||||
|
||||
.. 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.::
|
||||
|
||||
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. :meth:`drain` can be used to flush the underlying buffer once writing is
|
||||
available::
|
||||
|
||||
stream.write(data)
|
||||
await stream.drain()
|
||||
|
||||
.. deprecated:: 3.8
|
||||
|
||||
It is recommended to directly await on the `write()` method instead::
|
||||
|
||||
await stream.write(data)
|
||||
|
||||
.. 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 `writelines()` method::
|
||||
|
||||
await stream.writelines(lines)
|
||||
|
||||
The ``await`` pauses the current coroutine until the data is written to the
|
||||
socket.
|
||||
|
||||
.. method:: write_eof()
|
||||
|
||||
Close the write end of the stream after the buffered write
|
||||
data is flushed.
|
||||
|
||||
|
||||
StreamMode
|
||||
==========
|
||||
|
|
@ -459,8 +629,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
|
||||
|
|
@ -504,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)
|
||||
|
|
|
|||
|
|
@ -70,6 +70,13 @@ 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 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.
|
||||
|
||||
The rest of the arguments are passed directly to `loop.create_connection()`.
|
||||
"""
|
||||
# Design note:
|
||||
# Don't use decorator approach but explicit non-async
|
||||
# function to fail fast and explicitly
|
||||
|
|
@ -108,6 +115,13 @@ async def _connect(host, port,
|
|||
|
||||
|
||||
def connect_read_pipe(pipe, *, limit=_DEFAULT_LIMIT):
|
||||
"""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.
|
||||
"""
|
||||
|
||||
# Design note:
|
||||
# Don't use decorator approach but explicit non-async
|
||||
# function to fail fast and explicitly
|
||||
|
|
@ -129,6 +143,13 @@ async def _connect_read_pipe(pipe, limit):
|
|||
|
||||
|
||||
def connect_write_pipe(pipe, *, limit=_DEFAULT_LIMIT):
|
||||
"""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.
|
||||
"""
|
||||
|
||||
# Design note:
|
||||
# Don't use decorator approach but explicit non-async
|
||||
# function to fail fast and explicitly
|
||||
|
|
|
|||
Loading…
Reference in New Issue