[Python-checkins] cpython (3.5): Issue #27700: Document AbstractEventLoop, not BaseEventLoop.
guido.van.rossum
python-checkins at python.org
Mon Aug 8 17:44:11 EDT 2016
https://hg.python.org/cpython/rev/87e3a58ed3c3
changeset: 102572:87e3a58ed3c3
branch: 3.5
parent: 102567:9f8666d2ff5d
user: Guido van Rossum <guido at python.org>
date: Mon Aug 08 09:41:21 2016 -0700
summary:
Issue #27700: Document AbstractEventLoop, not BaseEventLoop.
files:
Doc/library/asyncio-dev.rst | 22 +-
Doc/library/asyncio-eventloop.rst | 133 +++++++++-------
Doc/library/asyncio-eventloops.rst | 28 +-
Doc/library/asyncio-protocol.rst | 18 +-
Doc/library/asyncio-stream.rst | 18 +-
Doc/library/asyncio-subprocess.rst | 26 +-
Doc/library/asyncio-task.rst | 22 +-
7 files changed, 138 insertions(+), 129 deletions(-)
diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -21,7 +21,7 @@
To enable all debug checks for an application:
* Enable the asyncio debug mode globally by setting the environment variable
- :envvar:`PYTHONASYNCIODEBUG` to ``1``, or by calling :meth:`BaseEventLoop.set_debug`.
+ :envvar:`PYTHONASYNCIODEBUG` to ``1``, or by calling :meth:`AbstractEventLoop.set_debug`.
* Set the log level of the :ref:`asyncio logger <asyncio-logger>` to
:py:data:`logging.DEBUG`. For example, call
``logging.basicConfig(level=logging.DEBUG)`` at startup.
@@ -33,18 +33,18 @@
* Log :ref:`coroutines defined but never "yielded from"
<asyncio-coroutine-not-scheduled>`
-* :meth:`~BaseEventLoop.call_soon` and :meth:`~BaseEventLoop.call_at` methods
+* :meth:`~AbstractEventLoop.call_soon` and :meth:`~AbstractEventLoop.call_at` methods
raise an exception if they are called from the wrong thread.
* Log the execution time of the selector
* Log callbacks taking more than 100 ms to be executed. The
- :attr:`BaseEventLoop.slow_callback_duration` attribute is the minimum
+ :attr:`AbstractEventLoop.slow_callback_duration` attribute is the minimum
duration in seconds of "slow" callbacks.
* :exc:`ResourceWarning` warnings are emitted when transports and event loops
are :ref:`not closed explicitly <asyncio-close-transports>`.
.. seealso::
- The :meth:`BaseEventLoop.set_debug` method and the :ref:`asyncio logger
+ The :meth:`AbstractEventLoop.set_debug` method and the :ref:`asyncio logger
<asyncio-logger>`.
@@ -68,7 +68,7 @@
Don't schedule directly a call to the :meth:`~Future.set_result` or the
:meth:`~Future.set_exception` method of a future with
-:meth:`BaseEventLoop.call_soon`: the future can be cancelled before its method
+:meth:`AbstractEventLoop.call_soon`: the future can be cancelled before its method
is called.
If you wait for a future, you should check early if the future was cancelled to
@@ -96,7 +96,7 @@
and the event loop executes the next task.
To schedule a callback from a different thread, the
-:meth:`BaseEventLoop.call_soon_threadsafe` method should be used. Example::
+:meth:`AbstractEventLoop.call_soon_threadsafe` method should be used. Example::
loop.call_soon_threadsafe(callback, *args)
@@ -116,7 +116,7 @@
future = asyncio.run_coroutine_threadsafe(coro_func(), loop)
result = future.result(timeout) # Wait for the result with a timeout
-The :meth:`BaseEventLoop.run_in_executor` method can be used with a thread pool
+The :meth:`AbstractEventLoop.run_in_executor` method can be used with a thread pool
executor to execute a callback in different thread to not block the thread of
the event loop.
@@ -145,7 +145,7 @@
An executor can be used to run a task in a different thread or even in a
different process, to not block the thread of the event loop. See the
-:meth:`BaseEventLoop.run_in_executor` method.
+:meth:`AbstractEventLoop.run_in_executor` method.
.. seealso::
@@ -168,7 +168,7 @@
----------------------------------------
When a coroutine function is called and its result is not passed to
-:func:`ensure_future` or to the :meth:`BaseEventLoop.create_task` method,
+:func:`ensure_future` or to the :meth:`AbstractEventLoop.create_task` method,
the execution of the coroutine object will never be scheduled which is
probably a bug. :ref:`Enable the debug mode of asyncio <asyncio-debug-mode>`
to :ref:`log a warning <asyncio-logger>` to detect it.
@@ -191,7 +191,7 @@
test()
The fix is to call the :func:`ensure_future` function or the
-:meth:`BaseEventLoop.create_task` method with the coroutine object.
+:meth:`AbstractEventLoop.create_task` method with the coroutine object.
.. seealso::
@@ -267,7 +267,7 @@
loop.run_forever()
loop.close()
-Another option is to use the :meth:`BaseEventLoop.run_until_complete`
+Another option is to use the :meth:`AbstractEventLoop.run_until_complete`
function::
task = asyncio.ensure_future(bug())
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -20,14 +20,23 @@
.. class:: BaseEventLoop
- Base class of event loops.
+ This class is an implementation detail. It is a subclass of
+ :class:`AbstractEventLoop` and may be a base class of concrete
+ event loop implementations found in :mod:`asyncio`. It should not
+ be used directly; use :class:`AbstractEventLoop` instead.
+ ``BaseEventLoop`` should not be subclassed by third-party code; the
+ internal interface is not stable.
+
+.. class:: AbstractEventLoop
+
+ Abstract base class of event loops.
This class is :ref:`not thread safe <asyncio-multithreading>`.
Run an event loop
-----------------
-.. method:: BaseEventLoop.run_forever()
+.. method:: AbstractEventLoop.run_forever()
Run until :meth:`stop` is called. If :meth:`stop` is called before
:meth:`run_forever()` is called, this polls the I/O selector once
@@ -40,7 +49,7 @@
.. versionchanged:: 3.5.1
-.. method:: BaseEventLoop.run_until_complete(future)
+.. method:: AbstractEventLoop.run_until_complete(future)
Run until the :class:`Future` is done.
@@ -49,11 +58,11 @@
Return the Future's result, or raise its exception.
-.. method:: BaseEventLoop.is_running()
+.. method:: AbstractEventLoop.is_running()
Returns running status of event loop.
-.. method:: BaseEventLoop.stop()
+.. method:: AbstractEventLoop.stop()
Stop running the event loop.
@@ -62,13 +71,13 @@
.. versionchanged:: 3.5.1
-.. method:: BaseEventLoop.is_closed()
+.. method:: AbstractEventLoop.is_closed()
Returns ``True`` if the event loop was closed.
.. versionadded:: 3.4.2
-.. method:: BaseEventLoop.close()
+.. method:: AbstractEventLoop.close()
Close the event loop. The loop must not be running. Pending
callbacks will be lost.
@@ -95,7 +104,7 @@
parameters in debug mode, whereas ``lambda`` functions have a poor
representation.
-.. method:: BaseEventLoop.call_soon(callback, \*args)
+.. method:: AbstractEventLoop.call_soon(callback, \*args)
Arrange for a callback to be called as soon as possible. The callback is
called after :meth:`call_soon` returns, when control returns to the event
@@ -113,7 +122,7 @@
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
-.. method:: BaseEventLoop.call_soon_threadsafe(callback, \*args)
+.. method:: AbstractEventLoop.call_soon_threadsafe(callback, \*args)
Like :meth:`call_soon`, but thread safe.
@@ -136,7 +145,7 @@
Timeouts (relative *delay* or absolute *when*) should not exceed one day.
-.. method:: BaseEventLoop.call_later(delay, callback, *args)
+.. method:: AbstractEventLoop.call_later(delay, callback, *args)
Arrange for the *callback* to be called after the given *delay*
seconds (either an int or float).
@@ -155,11 +164,11 @@
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
-.. method:: BaseEventLoop.call_at(when, callback, *args)
+.. method:: AbstractEventLoop.call_at(when, callback, *args)
Arrange for the *callback* to be called at the given absolute timestamp
*when* (an int or float), using the same time reference as
- :meth:`BaseEventLoop.time`.
+ :meth:`AbstractEventLoop.time`.
This method's behavior is the same as :meth:`call_later`.
@@ -169,7 +178,7 @@
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
-.. method:: BaseEventLoop.time()
+.. method:: AbstractEventLoop.time()
Return the current time, as a :class:`float` value, according to the
event loop's internal clock.
@@ -182,7 +191,7 @@
Futures
-------
-.. method:: BaseEventLoop.create_future()
+.. method:: AbstractEventLoop.create_future()
Create an :class:`asyncio.Future` object attached to the loop.
@@ -196,7 +205,7 @@
Tasks
-----
-.. method:: BaseEventLoop.create_task(coro)
+.. method:: AbstractEventLoop.create_task(coro)
Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in
a future. Return a :class:`Task` object.
@@ -210,10 +219,10 @@
.. versionadded:: 3.4.2
-.. method:: BaseEventLoop.set_task_factory(factory)
+.. method:: AbstractEventLoop.set_task_factory(factory)
Set a task factory that will be used by
- :meth:`BaseEventLoop.create_task`.
+ :meth:`AbstractEventLoop.create_task`.
If *factory* is ``None`` the default task factory will be set.
@@ -224,7 +233,7 @@
.. versionadded:: 3.4.4
-.. method:: BaseEventLoop.get_task_factory()
+.. method:: AbstractEventLoop.get_task_factory()
Return a task factory, or ``None`` if the default one is in use.
@@ -234,7 +243,7 @@
Creating connections
--------------------
-.. coroutinemethod:: BaseEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)
+.. coroutinemethod:: AbstractEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)
Create a streaming transport connection to a given Internet *host* and
*port*: socket family :py:data:`~socket.AF_INET` or
@@ -309,7 +318,7 @@
(:class:`StreamReader`, :class:`StreamWriter`) instead of a protocol.
-.. coroutinemethod:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
+.. coroutinemethod:: AbstractEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
Create datagram connection: socket family :py:data:`~socket.AF_INET` or
:py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
@@ -360,7 +369,7 @@
:ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
-.. coroutinemethod:: BaseEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
+.. coroutinemethod:: AbstractEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
Create UNIX connection: socket family :py:data:`~socket.AF_UNIX`, socket
type :py:data:`~socket.SOCK_STREAM`. The :py:data:`~socket.AF_UNIX` socket
@@ -371,7 +380,7 @@
establish the connection in the background. When successful, the
coroutine returns a ``(transport, protocol)`` pair.
- See the :meth:`BaseEventLoop.create_connection` method for parameters.
+ See the :meth:`AbstractEventLoop.create_connection` method for parameters.
Availability: UNIX.
@@ -379,7 +388,7 @@
Creating listening connections
------------------------------
-.. coroutinemethod:: BaseEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None)
+.. coroutinemethod:: AbstractEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None)
Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) bound to
*host* and *port*.
@@ -439,9 +448,9 @@
The *host* parameter can now be a sequence of strings.
-.. coroutinemethod:: BaseEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None)
+.. coroutinemethod:: AbstractEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None)
- Similar to :meth:`BaseEventLoop.create_server`, but specific to the
+ Similar to :meth:`AbstractEventLoop.create_server`, but specific to the
socket family :py:data:`~socket.AF_UNIX`.
This method is a :ref:`coroutine <coroutine>`.
@@ -457,7 +466,7 @@
On Windows with :class:`ProactorEventLoop`, these methods are not supported.
-.. method:: BaseEventLoop.add_reader(fd, callback, \*args)
+.. method:: AbstractEventLoop.add_reader(fd, callback, \*args)
Start watching the file descriptor for read availability and then call the
*callback* with specified arguments.
@@ -465,11 +474,11 @@
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
-.. method:: BaseEventLoop.remove_reader(fd)
+.. method:: AbstractEventLoop.remove_reader(fd)
Stop watching the file descriptor for read availability.
-.. method:: BaseEventLoop.add_writer(fd, callback, \*args)
+.. method:: AbstractEventLoop.add_writer(fd, callback, \*args)
Start watching the file descriptor for write availability and then call the
*callback* with specified arguments.
@@ -477,19 +486,19 @@
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
-.. method:: BaseEventLoop.remove_writer(fd)
+.. method:: AbstractEventLoop.remove_writer(fd)
Stop watching the file descriptor for write availability.
The :ref:`watch a file descriptor for read events <asyncio-watch-read-event>`
-example uses the low-level :meth:`BaseEventLoop.add_reader` method to register
+example uses the low-level :meth:`AbstractEventLoop.add_reader` method to register
the file descriptor of a socket.
Low-level socket operations
---------------------------
-.. coroutinemethod:: BaseEventLoop.sock_recv(sock, nbytes)
+.. coroutinemethod:: AbstractEventLoop.sock_recv(sock, nbytes)
Receive data from the socket. Modeled after blocking
:meth:`socket.socket.recv` method.
@@ -503,7 +512,7 @@
This method is a :ref:`coroutine <coroutine>`.
-.. coroutinemethod:: BaseEventLoop.sock_sendall(sock, data)
+.. coroutinemethod:: AbstractEventLoop.sock_sendall(sock, data)
Send data to the socket. Modeled after blocking
:meth:`socket.socket.sendall` method.
@@ -519,7 +528,7 @@
This method is a :ref:`coroutine <coroutine>`.
-.. coroutinemethod:: BaseEventLoop.sock_connect(sock, address)
+.. coroutinemethod:: AbstractEventLoop.sock_connect(sock, address)
Connect to a remote socket at *address*. Modeled after
blocking :meth:`socket.socket.connect` method.
@@ -533,16 +542,16 @@
``address`` no longer needs to be resolved. ``sock_connect``
will try to check if the *address* is already resolved by calling
:func:`socket.inet_pton`. If not,
- :meth:`BaseEventLoop.getaddrinfo` will be used to resolve the
+ :meth:`AbstractEventLoop.getaddrinfo` will be used to resolve the
*address*.
.. seealso::
- :meth:`BaseEventLoop.create_connection`
+ :meth:`AbstractEventLoop.create_connection`
and :func:`asyncio.open_connection() <open_connection>`.
-.. coroutinemethod:: BaseEventLoop.sock_accept(sock)
+.. coroutinemethod:: AbstractEventLoop.sock_accept(sock)
Accept a connection. Modeled after blocking
:meth:`socket.socket.accept`.
@@ -559,18 +568,18 @@
.. seealso::
- :meth:`BaseEventLoop.create_server` and :func:`start_server`.
+ :meth:`AbstractEventLoop.create_server` and :func:`start_server`.
Resolve host name
-----------------
-.. coroutinemethod:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
+.. coroutinemethod:: AbstractEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
This method is a :ref:`coroutine <coroutine>`, similar to
:meth:`socket.getaddrinfo` function but non-blocking.
-.. coroutinemethod:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
+.. coroutinemethod:: AbstractEventLoop.getnameinfo(sockaddr, flags=0)
This method is a :ref:`coroutine <coroutine>`, similar to
:meth:`socket.getnameinfo` function but non-blocking.
@@ -582,7 +591,7 @@
On Windows with :class:`SelectorEventLoop`, these methods are not supported.
Use :class:`ProactorEventLoop` to support pipes on Windows.
-.. coroutinemethod:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
+.. coroutinemethod:: AbstractEventLoop.connect_read_pipe(protocol_factory, pipe)
Register read pipe in eventloop.
@@ -596,7 +605,7 @@
This method is a :ref:`coroutine <coroutine>`.
-.. coroutinemethod:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
+.. coroutinemethod:: AbstractEventLoop.connect_write_pipe(protocol_factory, pipe)
Register write pipe in eventloop.
@@ -612,8 +621,8 @@
.. seealso::
- The :meth:`BaseEventLoop.subprocess_exec` and
- :meth:`BaseEventLoop.subprocess_shell` methods.
+ The :meth:`AbstractEventLoop.subprocess_exec` and
+ :meth:`AbstractEventLoop.subprocess_shell` methods.
UNIX signals
@@ -621,7 +630,7 @@
Availability: UNIX only.
-.. method:: BaseEventLoop.add_signal_handler(signum, callback, \*args)
+.. method:: AbstractEventLoop.add_signal_handler(signum, callback, \*args)
Add a handler for a signal.
@@ -631,7 +640,7 @@
:ref:`Use functools.partial to pass keywords to the callback
<asyncio-pass-keywords>`.
-.. method:: BaseEventLoop.remove_signal_handler(sig)
+.. method:: AbstractEventLoop.remove_signal_handler(sig)
Remove a handler for a signal.
@@ -649,7 +658,7 @@
pool of processes). By default, an event loop uses a thread pool executor
(:class:`~concurrent.futures.ThreadPoolExecutor`).
-.. coroutinemethod:: BaseEventLoop.run_in_executor(executor, func, \*args)
+.. coroutinemethod:: AbstractEventLoop.run_in_executor(executor, func, \*args)
Arrange for a *func* to be called in the specified executor.
@@ -661,7 +670,7 @@
This method is a :ref:`coroutine <coroutine>`.
-.. method:: BaseEventLoop.set_default_executor(executor)
+.. method:: AbstractEventLoop.set_default_executor(executor)
Set the default executor used by :meth:`run_in_executor`.
@@ -671,7 +680,7 @@
Allows customizing how exceptions are handled in the event loop.
-.. method:: BaseEventLoop.set_exception_handler(handler)
+.. method:: AbstractEventLoop.set_exception_handler(handler)
Set *handler* as the new event loop exception handler.
@@ -684,14 +693,14 @@
will be a ``dict`` object (see :meth:`call_exception_handler`
documentation for details about context).
-.. method:: BaseEventLoop.get_exception_handler()
+.. method:: AbstractEventLoop.get_exception_handler()
Return the exception handler, or ``None`` if the default one
is in use.
.. versionadded:: 3.5.2
-.. method:: BaseEventLoop.default_exception_handler(context)
+.. method:: AbstractEventLoop.default_exception_handler(context)
Default exception handler.
@@ -702,7 +711,7 @@
*context* parameter has the same meaning as in
:meth:`call_exception_handler`.
-.. method:: BaseEventLoop.call_exception_handler(context)
+.. method:: AbstractEventLoop.call_exception_handler(context)
Call the current event loop exception handler.
@@ -726,7 +735,7 @@
Debug mode
----------
-.. method:: BaseEventLoop.get_debug()
+.. method:: AbstractEventLoop.get_debug()
Get the debug mode (:class:`bool`) of the event loop.
@@ -736,7 +745,7 @@
.. versionadded:: 3.4.2
-.. method:: BaseEventLoop.set_debug(enabled: bool)
+.. method:: AbstractEventLoop.set_debug(enabled: bool)
Set the debug mode of the event loop.
@@ -753,7 +762,7 @@
Server listening on sockets.
- Object created by the :meth:`BaseEventLoop.create_server` method and the
+ Object created by the :meth:`AbstractEventLoop.create_server` method and the
:func:`start_server` function. Don't instantiate the class directly.
.. method:: close()
@@ -784,9 +793,9 @@
.. class:: Handle
- A callback wrapper object returned by :func:`BaseEventLoop.call_soon`,
- :func:`BaseEventLoop.call_soon_threadsafe`, :func:`BaseEventLoop.call_later`,
- and :func:`BaseEventLoop.call_at`.
+ A callback wrapper object returned by :func:`AbstractEventLoop.call_soon`,
+ :func:`AbstractEventLoop.call_soon_threadsafe`, :func:`AbstractEventLoop.call_later`,
+ and :func:`AbstractEventLoop.call_at`.
.. method:: cancel()
@@ -802,7 +811,7 @@
Hello World with call_soon()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Example using the :meth:`BaseEventLoop.call_soon` method to schedule a
+Example using the :meth:`AbstractEventLoop.call_soon` method to schedule a
callback. The callback displays ``"Hello World"`` and then stops the event
loop::
@@ -833,7 +842,7 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Example of callback displaying the current date every second. The callback uses
-the :meth:`BaseEventLoop.call_later` method to reschedule itself during 5
+the :meth:`AbstractEventLoop.call_later` method to reschedule itself during 5
seconds, and then stops the event loop::
import asyncio
@@ -869,7 +878,7 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Wait until a file descriptor received some data using the
-:meth:`BaseEventLoop.add_reader` method and then close the event loop::
+:meth:`AbstractEventLoop.add_reader` method and then close the event loop::
import asyncio
try:
@@ -907,7 +916,7 @@
The :ref:`register an open socket to wait for data using a protocol
<asyncio-register-socket>` example uses a low-level protocol created by the
- :meth:`BaseEventLoop.create_connection` method.
+ :meth:`AbstractEventLoop.create_connection` method.
The :ref:`register an open socket to wait for data using streams
<asyncio-register-socket-streams>` example uses high-level streams
@@ -918,7 +927,7 @@
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Register handlers for signals :py:data:`SIGINT` and :py:data:`SIGTERM` using
-the :meth:`BaseEventLoop.add_signal_handler` method::
+the :meth:`AbstractEventLoop.add_signal_handler` method::
import asyncio
import functools
diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst
--- a/Doc/library/asyncio-eventloops.rst
+++ b/Doc/library/asyncio-eventloops.rst
@@ -35,7 +35,7 @@
.. class:: SelectorEventLoop
Event loop based on the :mod:`selectors` module. Subclass of
- :class:`BaseEventLoop`.
+ :class:`AbstractEventLoop`.
Use the most efficient selector available on the platform.
@@ -46,7 +46,7 @@
.. class:: ProactorEventLoop
Proactor event loop for Windows using "I/O Completion Ports" aka IOCP.
- Subclass of :class:`BaseEventLoop`.
+ Subclass of :class:`AbstractEventLoop`.
Availability: Windows.
@@ -76,11 +76,11 @@
Common limits of Windows event loops:
-- :meth:`~BaseEventLoop.create_unix_connection` and
- :meth:`~BaseEventLoop.create_unix_server` are not supported: the socket
+- :meth:`~AbstractEventLoop.create_unix_connection` and
+ :meth:`~AbstractEventLoop.create_unix_server` are not supported: the socket
family :data:`socket.AF_UNIX` is specific to UNIX
-- :meth:`~BaseEventLoop.add_signal_handler` and
- :meth:`~BaseEventLoop.remove_signal_handler` are not supported
+- :meth:`~AbstractEventLoop.add_signal_handler` and
+ :meth:`~AbstractEventLoop.remove_signal_handler` are not supported
- :meth:`EventLoopPolicy.set_child_watcher` is not supported.
:class:`ProactorEventLoop` supports subprocesses. It has only one
implementation to watch child processes, there is no need to configure it.
@@ -89,19 +89,19 @@
- :class:`~selectors.SelectSelector` is used which only supports sockets
and is limited to 512 sockets.
-- :meth:`~BaseEventLoop.add_reader` and :meth:`~BaseEventLoop.add_writer` only
+- :meth:`~AbstractEventLoop.add_reader` and :meth:`~AbstractEventLoop.add_writer` only
accept file descriptors of sockets
- Pipes are not supported
- (ex: :meth:`~BaseEventLoop.connect_read_pipe`,
- :meth:`~BaseEventLoop.connect_write_pipe`)
+ (ex: :meth:`~AbstractEventLoop.connect_read_pipe`,
+ :meth:`~AbstractEventLoop.connect_write_pipe`)
- :ref:`Subprocesses <asyncio-subprocess>` are not supported
- (ex: :meth:`~BaseEventLoop.subprocess_exec`,
- :meth:`~BaseEventLoop.subprocess_shell`)
+ (ex: :meth:`~AbstractEventLoop.subprocess_exec`,
+ :meth:`~AbstractEventLoop.subprocess_shell`)
:class:`ProactorEventLoop` specific limits:
-- :meth:`~BaseEventLoop.create_datagram_endpoint` (UDP) is not supported
-- :meth:`~BaseEventLoop.add_reader` and :meth:`~BaseEventLoop.add_writer` are
+- :meth:`~AbstractEventLoop.create_datagram_endpoint` (UDP) is not supported
+- :meth:`~AbstractEventLoop.add_reader` and :meth:`~AbstractEventLoop.add_writer` are
not supported
The resolution of the monotonic clock on Windows is usually around 15.6 msec.
@@ -167,7 +167,7 @@
Get the event loop for the current context.
- Returns an event loop object implementing the :class:`BaseEventLoop`
+ Returns an event loop object implementing the :class:`AbstractEventLoop`
interface.
Raises an exception in case no event loop has been set for the current
diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -11,7 +11,7 @@
Transports are classes provided by :mod:`asyncio` in order to abstract
various kinds of communication channels. You generally won't instantiate
-a transport yourself; instead, you will call a :class:`BaseEventLoop` method
+a transport yourself; instead, you will call a :class:`AbstractEventLoop` method
which will create the transport and try to initiate the underlying
communication channel, calling you back when it succeeds.
@@ -475,7 +475,7 @@
TCP echo client protocol
------------------------
-TCP echo client using the :meth:`BaseEventLoop.create_connection` method, send
+TCP echo client using the :meth:`AbstractEventLoop.create_connection` method, send
data and wait until the connection is closed::
import asyncio
@@ -506,10 +506,10 @@
loop.close()
The event loop is running twice. The
-:meth:`~BaseEventLoop.run_until_complete` method is preferred in this short
+:meth:`~AbstractEventLoop.run_until_complete` method is preferred in this short
example to raise an exception if the server is not listening, instead of
having to write a short coroutine to handle the exception and stop the
-running loop. At :meth:`~BaseEventLoop.run_until_complete` exit, the loop is
+running loop. At :meth:`~AbstractEventLoop.run_until_complete` exit, the loop is
no longer running, so there is no need to stop the loop in case of an error.
.. seealso::
@@ -523,7 +523,7 @@
TCP echo server protocol
------------------------
-TCP echo server using the :meth:`BaseEventLoop.create_server` method, send back
+TCP echo server using the :meth:`AbstractEventLoop.create_server` method, send back
received data and close the connection::
import asyncio
@@ -577,7 +577,7 @@
UDP echo client protocol
------------------------
-UDP echo client using the :meth:`BaseEventLoop.create_datagram_endpoint`
+UDP echo client using the :meth:`AbstractEventLoop.create_datagram_endpoint`
method, send data and close the transport when we received the answer::
import asyncio
@@ -623,7 +623,7 @@
UDP echo server protocol
------------------------
-UDP echo server using the :meth:`BaseEventLoop.create_datagram_endpoint`
+UDP echo server using the :meth:`AbstractEventLoop.create_datagram_endpoint`
method, send back received data::
import asyncio
@@ -660,7 +660,7 @@
---------------------------------------------------------
Wait until a socket receives data using the
-:meth:`BaseEventLoop.create_connection` method with a protocol, and then close
+:meth:`AbstractEventLoop.create_connection` method with a protocol, and then close
the event loop ::
import asyncio
@@ -708,7 +708,7 @@
The :ref:`watch a file descriptor for read events
<asyncio-watch-read-event>` example uses the low-level
- :meth:`BaseEventLoop.add_reader` method to register the file descriptor of a
+ :meth:`AbstractEventLoop.add_reader` method to register the file descriptor of a
socket.
The :ref:`register an open socket to wait for data using streams
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -18,14 +18,14 @@
.. coroutinefunction:: open_connection(host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
- A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader,
+ A wrapper for :meth:`~AbstractEventLoop.create_connection()` returning a (reader,
writer) pair.
The reader returned is a :class:`StreamReader` instance; the writer is
a :class:`StreamWriter` instance.
The arguments are all the usual arguments to
- :meth:`BaseEventLoop.create_connection` except *protocol_factory*; most
+ :meth:`AbstractEventLoop.create_connection` except *protocol_factory*; most
common are positional host and port, with various optional keyword arguments
following.
@@ -38,7 +38,7 @@
.. coroutinefunction:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
Start a socket server, with a callback for each client connected. The return
- value is the same as :meth:`~BaseEventLoop.create_server()`.
+ value is the same as :meth:`~AbstractEventLoop.create_server()`.
The *client_connected_cb* parameter is called with two parameters:
*client_reader*, *client_writer*. *client_reader* is a
@@ -49,7 +49,7 @@
converted into a :class:`Task`.
The rest of the arguments are all the usual arguments to
- :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
+ :meth:`~AbstractEventLoop.create_server()` except *protocol_factory*; most
common are positional *host* and *port*, with various optional keyword
arguments following.
@@ -61,7 +61,7 @@
.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
- A wrapper for :meth:`~BaseEventLoop.create_unix_connection()` returning
+ A wrapper for :meth:`~AbstractEventLoop.create_unix_connection()` returning
a (reader, writer) pair.
See :func:`open_connection` for information about return value and other
@@ -321,7 +321,7 @@
.. seealso::
The :ref:`TCP echo client protocol <asyncio-tcp-echo-client-protocol>`
- example uses the :meth:`BaseEventLoop.create_connection` method.
+ example uses the :meth:`AbstractEventLoop.create_connection` method.
.. _asyncio-tcp-echo-server-streams:
@@ -366,7 +366,7 @@
.. seealso::
The :ref:`TCP echo server protocol <asyncio-tcp-echo-server-protocol>`
- example uses the :meth:`BaseEventLoop.create_server` method.
+ example uses the :meth:`AbstractEventLoop.create_server` method.
Get HTTP headers
@@ -458,10 +458,10 @@
The :ref:`register an open socket to wait for data using a protocol
<asyncio-register-socket>` example uses a low-level protocol created by the
- :meth:`BaseEventLoop.create_connection` method.
+ :meth:`AbstractEventLoop.create_connection` method.
The :ref:`watch a file descriptor for read events
<asyncio-watch-read-event>` example uses the low-level
- :meth:`BaseEventLoop.add_reader` method to register the file descriptor of a
+ :meth:`AbstractEventLoop.add_reader` method to register the file descriptor of a
socket.
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -32,7 +32,7 @@
Create a subprocess.
The *limit* parameter sets the buffer limit passed to the
- :class:`StreamReader`. See :meth:`BaseEventLoop.subprocess_exec` for other
+ :class:`StreamReader`. See :meth:`AbstractEventLoop.subprocess_exec` for other
parameters.
Return a :class:`~asyncio.subprocess.Process` instance.
@@ -44,7 +44,7 @@
Run the shell command *cmd*.
The *limit* parameter sets the buffer limit passed to the
- :class:`StreamReader`. See :meth:`BaseEventLoop.subprocess_shell` for other
+ :class:`StreamReader`. See :meth:`AbstractEventLoop.subprocess_shell` for other
parameters.
Return a :class:`~asyncio.subprocess.Process` instance.
@@ -58,8 +58,8 @@
This function is a :ref:`coroutine <coroutine>`.
-Use the :meth:`BaseEventLoop.connect_read_pipe` and
-:meth:`BaseEventLoop.connect_write_pipe` methods to connect pipes.
+Use the :meth:`AbstractEventLoop.connect_read_pipe` and
+:meth:`AbstractEventLoop.connect_write_pipe` methods to connect pipes.
Create a subprocess: low-level API using subprocess.Popen
@@ -67,7 +67,7 @@
Run subprocesses asynchronously using the :mod:`subprocess` module.
-.. coroutinemethod:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
+.. coroutinemethod:: AbstractEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
Create a subprocess from one or more string arguments (character strings or
bytes strings encoded to the :ref:`filesystem encoding
@@ -87,19 +87,19 @@
* *stdin*: Either a file-like object representing the pipe to be connected
to the subprocess's standard input stream using
- :meth:`~BaseEventLoop.connect_write_pipe`, or the constant
+ :meth:`~AbstractEventLoop.connect_write_pipe`, or the constant
:const:`subprocess.PIPE` (the default). By default a new pipe will be
created and connected.
* *stdout*: Either a file-like object representing the pipe to be connected
to the subprocess's standard output stream using
- :meth:`~BaseEventLoop.connect_read_pipe`, or the constant
+ :meth:`~AbstractEventLoop.connect_read_pipe`, or the constant
:const:`subprocess.PIPE` (the default). By default a new pipe will be
created and connected.
* *stderr*: Either a file-like object representing the pipe to be connected
to the subprocess's standard error stream using
- :meth:`~BaseEventLoop.connect_read_pipe`, or one of the constants
+ :meth:`~AbstractEventLoop.connect_read_pipe`, or one of the constants
:const:`subprocess.PIPE` (the default) or :const:`subprocess.STDOUT`.
By default a new pipe will be created and connected. When
:const:`subprocess.STDOUT` is specified, the subprocess's standard error
@@ -116,7 +116,7 @@
See the constructor of the :class:`subprocess.Popen` class for parameters.
-.. coroutinemethod:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
+.. coroutinemethod:: AbstractEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
Create a subprocess from *cmd*, which is a character string or a bytes
string encoded to the :ref:`filesystem encoding <filesystem-encoding>`,
@@ -126,7 +126,7 @@
The *protocol_factory* must instanciate a subclass of the
:class:`asyncio.SubprocessProtocol` class.
- See :meth:`~BaseEventLoop.subprocess_exec` for more details about
+ See :meth:`~AbstractEventLoop.subprocess_exec` for more details about
the remaining arguments.
Returns a pair of ``(transport, protocol)``, where *transport* is an
@@ -143,8 +143,8 @@
.. seealso::
- The :meth:`BaseEventLoop.connect_read_pipe` and
- :meth:`BaseEventLoop.connect_write_pipe` methods.
+ The :meth:`AbstractEventLoop.connect_read_pipe` and
+ :meth:`AbstractEventLoop.connect_write_pipe` methods.
Constants
@@ -329,7 +329,7 @@
Example of a subprocess protocol using to get the output of a subprocess and to
wait for the subprocess exit. The subprocess is created by the
-:meth:`BaseEventLoop.subprocess_exec` method::
+:meth:`AbstractEventLoop.subprocess_exec` method::
import asyncio
import sys
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -59,7 +59,7 @@
schedule its execution. There are two basic ways to start it running:
call ``await coroutine`` or ``yield from coroutine`` from another coroutine
(assuming the other coroutine is already running!), or schedule its execution
-using the :func:`ensure_future` function or the :meth:`BaseEventLoop.create_task`
+using the :func:`ensure_future` function or the :meth:`AbstractEventLoop.create_task`
method.
@@ -108,7 +108,7 @@
.. seealso::
The :ref:`Hello World with call_soon() <asyncio-hello-world-callback>`
- example uses the :meth:`BaseEventLoop.call_soon` method to schedule a
+ example uses the :meth:`AbstractEventLoop.call_soon` method to schedule a
callback.
@@ -151,7 +151,7 @@
The :ref:`display the current date with call_later()
<asyncio-date-callback>` example uses a callback with the
- :meth:`BaseEventLoop.call_later` method.
+ :meth:`AbstractEventLoop.call_later` method.
Example: Chain coroutines
@@ -182,12 +182,12 @@
.. image:: tulip_coro.png
:align: center
-The "Task" is created by the :meth:`BaseEventLoop.run_until_complete` method
+The "Task" is created by the :meth:`AbstractEventLoop.run_until_complete` method
when it gets a coroutine object instead of a task.
The diagram shows the control flow, it does not describe exactly how things
work internally. For example, the sleep coroutine creates an internal future
-which uses :meth:`BaseEventLoop.call_later` to wake up the task in 1 second.
+which uses :meth:`AbstractEventLoop.call_later` to wake up the task in 1 second.
InvalidStateError
@@ -223,7 +223,7 @@
raise an exception when the future isn't done yet.
- Callbacks registered with :meth:`add_done_callback` are always called
- via the event loop's :meth:`~BaseEventLoop.call_soon_threadsafe`.
+ via the event loop's :meth:`~AbstractEventLoop.call_soon_threadsafe`.
- This class is not compatible with the :func:`~concurrent.futures.wait` and
:func:`~concurrent.futures.as_completed` functions in the
@@ -273,7 +273,7 @@
The callback is called with a single argument - the future object. If the
future is already done when this is called, the callback is scheduled
- with :meth:`~BaseEventLoop.call_soon`.
+ with :meth:`~AbstractEventLoop.call_soon`.
:ref:`Use functools.partial to pass parameters to the callback
<asyncio-pass-keywords>`. For example,
@@ -323,11 +323,11 @@
The coroutine function is responsible for the computation (which takes 1 second)
and it stores the result into the future. The
-:meth:`~BaseEventLoop.run_until_complete` method waits for the completion of
+:meth:`~AbstractEventLoop.run_until_complete` method waits for the completion of
the future.
.. note::
- The :meth:`~BaseEventLoop.run_until_complete` method uses internally the
+ The :meth:`~AbstractEventLoop.run_until_complete` method uses internally the
:meth:`~Future.add_done_callback` method to be notified when the future is
done.
@@ -396,7 +396,7 @@
logged: see :ref:`Pending task destroyed <asyncio-pending-task-destroyed>`.
Don't directly create :class:`Task` instances: use the :func:`ensure_future`
- function or the :meth:`BaseEventLoop.create_task` method.
+ function or the :meth:`AbstractEventLoop.create_task` method.
This class is :ref:`not thread safe <asyncio-multithreading>`.
@@ -546,7 +546,7 @@
.. seealso::
- The :meth:`BaseEventLoop.create_task` method.
+ The :meth:`AbstractEventLoop.create_task` method.
.. function:: async(coro_or_future, \*, loop=None)
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list