bpo-33736: Improve the documentation of asyncio stream APIs (GH-7326) · python/cpython@c0d062f (original) (raw)
`@@ -18,72 +18,110 @@ Stream functions
`
18
18
` exactly what you want, feel free to copy their code.
`
19
19
``
20
20
``
21
``
`-
.. coroutinefunction:: open_connection(host=None, port=None, *, loop=None, limit=None, **kwds)
`
``
21
`+
.. coroutinefunction:: open_connection(host=None, port=None, *, loop=None, limit=None, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None)
`
22
22
``
23
23
`` A wrapper for :meth:~AbstractEventLoop.create_connection() returning a (reader,
``
24
24
` writer) pair.
`
25
25
``
26
26
`` The reader returned is a :class:StreamReader instance; the writer is
``
27
27
`` a :class:StreamWriter instance.
``
28
28
``
29
``
`-
The arguments are all the usual arguments to
`
30
``
`` -
:meth:AbstractEventLoop.create_connection except protocol_factory; most
``
31
``
`-
common are positional host and port, with various optional keyword arguments
`
32
``
`-
following.
`
``
29
`+
When specified, the loop argument determines which event loop to use,
`
``
30
`+
and the limit argument determines the buffer size limit used by the
`
``
31
`` +
returned :class:StreamReader instance.
``
33
32
``
34
``
`-
Additional optional keyword arguments are loop (to set the event loop
`
35
``
`-
instance to use) and limit (to set the buffer limit passed to the
`
36
``
`` -
:class:StreamReader).
``
``
33
`+
The rest of the arguments are passed directly to
`
``
34
`` +
:meth:AbstractEventLoop.create_connection.
``
37
35
``
38
36
`` This function is a :ref:coroutine <coroutine>.
``
39
37
``
40
``
`-
.. coroutinefunction:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=None, **kwds)
`
``
38
`+
.. versionadded:: 3.7
`
``
39
+
``
40
`+
The ssl_handshake_timeout parameter.
`
``
41
+
``
42
`+
.. coroutinefunction:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=None, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)
`
41
43
``
42
44
` Start a socket server, with a callback for each client connected. The return
`
43
45
`` value is the same as :meth:~AbstractEventLoop.create_server().
``
44
46
``
45
``
`-
The client_connected_cb parameter is called with two parameters:
`
46
``
`-
client_reader, client_writer. client_reader is a
`
47
``
`` -
:class:StreamReader object, while client_writer is a
``
48
``
`` -
:class:StreamWriter object. The client_connected_cb parameter can
``
49
``
`` -
either be a plain callback function or a :ref:`coroutine function
``
50
``
`` -
`; if it is a coroutine function, it will be automatically
``
51
``
`` -
converted into a :class:Task.
``
``
47
`+
The client_connected_cb callback is called whenever a new client
`
``
48
`+
connection is established. It receives a reader/writer pair as two
`
``
49
`` +
arguments, the first is a :class:StreamReader instance,
``
``
50
`` +
and the second is a :class:StreamWriter instance.
``
``
51
+
``
52
`+
client_connected_cb accepts a plain callable or a
`
``
53
`` +
:ref:coroutine function <coroutine>; if it is a coroutine function,
``
``
54
`` +
it will be automatically converted into a :class:Task.
``
52
55
``
53
``
`-
The rest of the arguments are all the usual arguments to
`
54
``
`` -
:meth:~AbstractEventLoop.create_server() except protocol_factory; most
``
55
``
`-
common are positional host and port, with various optional keyword
`
56
``
`-
arguments following.
`
``
56
`+
When specified, the loop argument determines which event loop to use,
`
``
57
`+
and the limit argument determines the buffer size limit used by the
`
``
58
`` +
:class:StreamReader instance passed to client_connected_cb.
``
57
59
``
58
``
`-
Additional optional keyword arguments are loop (to set the event loop
`
59
``
`-
instance to use) and limit (to set the buffer limit passed to the
`
60
``
`` -
:class:StreamReader).
``
``
60
`+
The rest of the arguments are passed directly to
`
``
61
`` +
:meth:~AbstractEventLoop.create_server().
``
61
62
``
62
63
`` This function is a :ref:coroutine <coroutine>.
``
63
64
``
64
``
`-
.. coroutinefunction:: open_unix_connection(path=None, *, loop=None, limit=None, **kwds)
`
``
65
`+
.. versionadded:: 3.7
`
``
66
+
``
67
`+
The ssl_handshake_timeout and start_serving parameters.
`
``
68
+
``
69
`+
.. coroutinefunction:: open_unix_connection(path=None, *, loop=None, limit=None, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)
`
65
70
``
66
71
`` A wrapper for :meth:~AbstractEventLoop.create_unix_connection() returning
``
67
72
` a (reader, writer) pair.
`
68
73
``
69
``
`` -
See :func:open_connection for information about return value and other
``
70
``
`-
details.
`
``
74
`+
When specified, the loop argument determines which event loop to use,
`
``
75
`+
and the limit argument determines the buffer size limit used by the
`
``
76
`` +
returned :class:StreamReader instance.
``
``
77
+
``
78
`+
The rest of the arguments are passed directly to
`
``
79
`` +
:meth:~AbstractEventLoop.create_unix_connection().
``
71
80
``
72
81
`` This function is a :ref:coroutine <coroutine>.
``
73
82
``
74
83
` Availability: UNIX.
`
75
84
``
76
``
`-
.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, *, loop=None, limit=None, **kwds)
`
``
85
`+
.. versionadded:: 3.7
`
``
86
+
``
87
`+
The ssl_handshake_timeout parameter.
`
``
88
+
``
89
`+
.. versionchanged:: 3.7
`
``
90
+
``
91
`` +
The path parameter can now be a :term:path-like object
``
``
92
+
``
93
`+
.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, *, loop=None, limit=None, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)
`
77
94
``
78
95
` Start a UNIX Domain Socket server, with a callback for each client connected.
`
79
96
``
80
``
`` -
See :func:start_server for information about return value and other
``
81
``
`-
details.
`
``
97
`+
The client_connected_cb callback is called whenever a new client
`
``
98
`+
connection is established. It receives a reader/writer pair as two
`
``
99
`` +
arguments, the first is a :class:StreamReader instance,
``
``
100
`` +
and the second is a :class:StreamWriter instance.
``
``
101
+
``
102
`+
client_connected_cb accepts a plain callable or a
`
``
103
`` +
:ref:coroutine function <coroutine>; if it is a coroutine function,
``
``
104
`` +
it will be automatically converted into a :class:Task.
``
``
105
+
``
106
`+
When specified, the loop argument determines which event loop to use,
`
``
107
`+
and the limit argument determines the buffer size limit used by the
`
``
108
`` +
:class:StreamReader instance passed to client_connected_cb.
``
``
109
+
``
110
`+
The rest of the arguments are passed directly to
`
``
111
`` +
:meth:~AbstractEventLoop.create_unix_server().
``
82
112
``
83
113
`` This function is a :ref:coroutine <coroutine>.
``
84
114
``
85
115
` Availability: UNIX.
`
86
116
``
``
117
`+
.. versionadded:: 3.7
`
``
118
+
``
119
`+
The ssl_handshake_timeout and start_serving parameters.
`
``
120
+
``
121
`+
.. versionchanged:: 3.7
`
``
122
+
``
123
`` +
The path parameter can now be a :term:path-like object.
``
``
124
+
87
125
``
88
126
`StreamReader
`
89
127
`============
`
`@@ -475,4 +513,3 @@ Coroutine waiting until a socket receives data using the
`
475
513
`` ` example uses the low-level
``
476
514
`` :meth:AbstractEventLoop.add_reader method to register the file descriptor of a
``
477
515
` socket.
`
478
``
-