bpo-33649: Add low-level APIs index. (GH-9364)
diff --git a/Doc/library/asyncio-llapi-index.rst b/Doc/library/asyncio-llapi-index.rst
new file mode 100644
index 0000000..7fb1e60
--- /dev/null
+++ b/Doc/library/asyncio-llapi-index.rst
@@ -0,0 +1,510 @@
+.. currentmodule:: asyncio
+
+
+===================
+Low-level API Index
+===================
+
+This page lists all low-level asyncio APIs.
+
+
+Obtaining the Event Loop
+========================
+
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :func:`asyncio.get_running_loop`
+ - The **preferred** function to get the running event loop.
+
+ * - :func:`asyncio.get_event_loop`
+ - Get an event loop instance (current or via the policy).
+
+ * - :func:`asyncio.set_event_loop`
+ - Set the event loop as current via the current policy.
+
+ * - :func:`asyncio.new_event_loop`
+ - Create a new event loop.
+
+
+.. rubric:: Examples
+
+* :ref:`Using asyncio.get_running_loop() <asyncio_example_future>`.
+
+
+Event Loop Methods
+==================
+
+See also the main documentation section about the
+:ref:`event loop methods <asyncio-event-loop>`.
+
+.. rubric:: Lifecycle
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`loop.run_until_complete`
+ - Run a Future/Task/awaitable until complete.
+
+ * - :meth:`loop.run_forever`
+ - Run the event loop forever.
+
+ * - :meth:`loop.stop`
+ - Stop the event loop.
+
+ * - :meth:`loop.stop`
+ - Close the event loop.
+
+ * - :meth:`loop.is_running()`
+ - Return ``True`` if the event loop is running.
+
+ * - :meth:`loop.is_closed()`
+ - Return ``True`` if the event loop is closed.
+
+ * - ``await`` :meth:`loop.shutdown_asyncgens`
+ - Close asynchronous generators.
+
+
+.. rubric:: Debugging
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`loop.set_debug`
+ - Enable or disable the debug mode.
+
+ * - :meth:`loop.get_debug`
+ - Get the current debug mode.
+
+
+.. rubric:: Scheduling Callbacks
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`loop.call_soon`
+ - Invoke a callback soon.
+
+ * - :meth:`loop.call_soon_threadsafe`
+ - A thread-safe variant of :meth:`loop.call_soon`.
+
+ * - :meth:`loop.call_later`
+ - Invoke a callback *after* the given time.
+
+ * - :meth:`loop.call_at`
+ - Invoke a callback *at* the given time.
+
+
+.. rubric:: Thread/Process Pool
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``await`` :meth:`loop.run_in_executor`
+ - Run a CPU-bound or other blocking function in
+ a :mod:`concurrent.futures` executor.
+
+ * - :meth:`loop.set_default_executor`
+ - Set the default executor for :meth:`loop.run_in_executor`.
+
+
+.. rubric:: Tasks and Futures
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`loop.create_future`
+ - Create a :class:`Future` object.
+
+ * - :meth:`loop.create_task`
+ - Schedule coroutine as a :class:`Task`.
+
+ * - :meth:`loop.set_task_factory`
+ - Set a factory used by :meth:`loop.create_task` to
+ create :class:`Tasks <Task>`.
+
+ * - :meth:`loop.get_task_factory`
+ - Get the factory :meth:`loop.create_task` uses
+ to create :class:`Tasks <Task>`.
+
+
+.. rubric:: DNS
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``await`` :meth:`loop.getaddrinfo`
+ - Asynchronous version of :meth:`socket.getaddrinfo`.
+
+ * - ``await`` :meth:`loop.getnameinfo`
+ - Asynchronous version of :meth:`socket.getnameinfo`.
+
+
+.. rubric:: Networking and IPC
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``await`` :meth:`loop.create_connection`
+ - Open a TCP connection.
+
+ * - ``await`` :meth:`loop.create_server`
+ - Create a TCP server.
+
+ * - ``await`` :meth:`loop.create_unix_connection`
+ - Open a Unix socket connection.
+
+ * - ``await`` :meth:`loop.create_unix_server`
+ - Create a Unix socket server.
+
+ * - ``await`` :meth:`loop.connect_accepted_socket`
+ - Wrap a :class:`~socket.socket` into a ``(transport, protocol)``
+ pair.
+
+ * - ``await`` :meth:`loop.create_datagram_endpoint`
+ - Open a datagram (UDP) connection.
+
+ * - ``await`` :meth:`loop.sendfile`
+ - Send a file over a transport.
+
+ * - ``await`` :meth:`loop.start_tls`
+ - Upgrade an existing connection to TLS.
+
+ * - ``await`` :meth:`loop.connect_read_pipe`
+ - Wrap a read end of a pipe into a ``(transport, protocol)`` pair.
+
+ * - ``await`` :meth:`loop.connect_write_pipe`
+ - Wrap a write end of a pipe into a ``(transport, protocol)`` pair.
+
+
+.. rubric:: Sockets
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``await`` :meth:`loop.sock_recv`
+ - Receive data from the :class:`~socket.socket`.
+
+ * - ``await`` :meth:`loop.sock_recv_into`
+ - Receive data from the :class:`~socket.socket` into a buffer.
+
+ * - ``await`` :meth:`loop.sock_sendall`
+ - Send data to the :class:`~socket.socket`.
+
+ * - ``await`` :meth:`loop.sock_connect`
+ - Connect the :class:`~socket.socket`.
+
+ * - ``await`` :meth:`loop.sock_accept`
+ - Accept a :class:`~socket.socket` connection.
+
+ * - ``await`` :meth:`loop.sock_sendfile`
+ - Send a file over the :class:`~socket.socket`.
+
+ * - :meth:`loop.add_reader`
+ - Start watching a file descriptor for read availability.
+
+ * - :meth:`loop.remove_reader`
+ - Stop watching a file descriptor for read availability.
+
+ * - :meth:`loop.add_writer`
+ - Start watching a file descriptor for write availability.
+
+ * - :meth:`loop.remove_writer`
+ - Stop watching a file descriptor for write availability.
+
+
+.. rubric:: Unix Signals
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`loop.add_signal_handler`
+ - Add a handler for a :mod:`signal`.
+
+ * - :meth:`loop.remove_signal_handler`
+ - Remove a handler for a :mod:`signal`.
+
+
+.. rubric:: Subprocesses
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`loop.subprocess_exec`
+ - Spawn a subprocess.
+
+ * - :meth:`loop.subprocess_shell`
+ - Spawn a subprocess from a shell command.
+
+
+.. rubric:: Error Handling
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`loop.call_exception_handler`
+ - Call the exception handler.
+
+ * - :meth:`loop.set_exception_handler`
+ - Set a new exception handler.
+
+ * - :meth:`loop.get_exception_handler`
+ - Get the current exception handler.
+
+ * - :meth:`loop.default_exception_handler`
+ - The default exception handler implementation.
+
+
+.. rubric:: Examples
+
+* :ref:`Using asyncio.get_event_loop() and loop.run_forever()
+ <asyncio_example_lowlevel_helloworld>`.
+
+* :ref:`Using loop.call_later() <asyncio_example_call_later>`.
+
+* Using ``loop.create_connection()`` to implement
+ :ref:`an echo-client <asyncio_example_tcp_echo_client_protocol>`.
+
+* Using ``loop.create_connection()`` to
+ :ref:`connect a socket <asyncio_example_create_connection>`.
+
+* :ref:`Using add_reader() to watch an FD for read events
+ <asyncio_example_watch_fd>`.
+
+* :ref:`Using loop.add_signal_handler() <asyncio_example_unix_signals>`.
+
+* :ref:`Using loop.subprocess_exec() <asyncio_example_subprocess_proto>`.
+
+
+Transports
+==========
+
+All transports implement the following methods:
+
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`transport.close() <BaseTransport.close>`
+ - Close the transport.
+
+ * - :meth:`transport.is_closing() <BaseTransport.is_closing>`
+ - Return ``True`` if the transport is closing or is closed.
+
+ * - :meth:`transport.get_extra_info() <BaseTransport.get_extra_info>`
+ - Request for information about the transport.
+
+ * - :meth:`transport.set_protocol() <BaseTransport.set_protocol>`
+ - Set a new protocol.
+
+ * - :meth:`transport.get_protocol() <BaseTransport.get_protocol>`
+ - Return the current protocol.
+
+
+Transports that can receive data (TCP and Unix connections,
+pipes, etc). Returned from methods like
+:meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
+:meth:`loop.connect_read_pipe`, etc:
+
+.. rubric:: Read Transports
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`transport.is_reading() <ReadTransport.is_reading>`
+ - Return ``True`` if the transport is receiving.
+
+ * - :meth:`transport.pause_reading() <ReadTransport.pause_reading>`
+ - Pause receiving.
+
+ * - :meth:`transport.resume_reading() <ReadTransport.resume_reading>`
+ - Resume receiving.
+
+
+Transports that can Send data (TCP and Unix connections,
+pipes, etc). Returned from methods like
+:meth:`loop.create_connection`, :meth:`loop.create_unix_connection`,
+:meth:`loop.connect_write_pipe`, etc:
+
+.. rubric:: Write Transports
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`transport.write() <WriteTransport.write>`
+ - Write data to the transport.
+
+ * - :meth:`transport.writelines() <WriteTransport.writelines>`
+ - Write buffers to the transport.
+
+ * - :meth:`transport.can_write_eof() <WriteTransport.can_write_eof>`
+ - Return :const:`True` if the transport supports sending EOF.
+
+ * - :meth:`transport.write_eof() <WriteTransport.write_eof>`
+ - Close and send EOF after flushing buffered data.
+
+ * - :meth:`transport.abort() <WriteTransport.abort>`
+ - Close the transport immediately.
+
+ * - :meth:`transport.get_write_buffer_size()
+ <WriteTransport.get_write_buffer_size>`
+ - Return high and low water marks for write flow control.
+
+ * - :meth:`transport.set_write_buffer_limits()
+ <WriteTransport.set_write_buffer_limits>`
+ - Set new high and low water marks for write flow control.
+
+
+Transports returned by :meth:`loop.create_datagram_endpoint`:
+
+.. rubric:: Datagram Transports
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`transport.sendto() <DatagramTransport.sendto>`
+ - Send data to the remote peer.
+
+ * - :meth:`transport.abort() <DatagramTransport.abort>`
+ - Close the transport immediately.
+
+
+Low-level transport abstraction over subprocesses.
+Returned by :meth:`loop.subprocess_exec` and
+:meth:`loop.subprocess_shell`:
+
+.. rubric:: Subprocess Transports
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`transport.get_pid() <SubprocessTransport.get_pid>`
+ - Return the subprocess process id.
+
+ * - :meth:`transport.get_pipe_transport()
+ <SubprocessTransport.get_pipe_transport>`
+ - Return the transport for the requested communication pipe
+ (*stdin*, *stdout*, or *stderr*).
+
+ * - :meth:`transport.get_returncode() <SubprocessTransport.get_returncode>`
+ - Return the subprocess return code.
+
+ * - :meth:`transport.kill() <SubprocessTransport.kill>`
+ - Kill the subprocess.
+
+ * - :meth:`transport.send_signal() <SubprocessTransport.send_signal>`
+ - Send a signal to the subprocess.
+
+ * - :meth:`transport.terminate() <SubprocessTransport.terminate>`
+ - Stop the subprocess.
+
+ * - :meth:`transport.close() <SubprocessTransport.close>`
+ - Kill the subprocess and close all pipes.
+
+
+Protocols
+=========
+
+Protocol classes can implement the following **callback methods**:
+
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``callback`` :meth:`connection_made() <BaseProtocol.connection_made>`
+ - Called when a connection is made.
+
+ * - ``callback`` :meth:`connection_lost() <BaseProtocol.connection_lost>`
+ - Called when the connection is lost or closed.
+
+ * - ``callback`` :meth:`pause_writing() <BaseProtocol.pause_writing>`
+ - Called when the transport's buffer goes over the high water mark.
+
+ * - ``callback`` :meth:`resume_writing() <BaseProtocol.resume_writing>`
+ - Called when the transport's buffer drains below the low water mark.
+
+
+.. rubric:: Streaming Protocols (TCP, Unix Sockets, Pipes)
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``callback`` :meth:`data_received() <Protocol.data_received>`
+ - Called when some data is received.
+
+ * - ``callback`` :meth:`eof_received() <Protocol.eof_received>`
+ - Called when an EOF is received.
+
+
+.. rubric:: Buffered Streaming Protocols
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``callback`` :meth:`get_buffer() <BufferedProtocol.get_buffer>`
+ - Called to allocate a new receive buffer.
+
+ * - ``callback`` :meth:`buffer_updated() <BufferedProtocol.buffer_updated>`
+ - Called when the buffer was updated with the received data.
+
+ * - ``callback`` :meth:`eof_received() <BufferedProtocol.eof_received>`
+ - Called when an EOF is received.
+
+
+.. rubric:: Datagram Protocols
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``callback`` :meth:`datagram_received()
+ <DatagramProtocol.datagram_received>`
+ - Called when a datagram is received.
+
+ * - ``callback`` :meth:`error_received() <DatagramProtocol.error_received>`
+ - Called when a previous send or receive operation raises an
+ :class:`OSError`.
+
+
+.. rubric:: Subprocess Protocols
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - ``callback`` :meth:`pipe_data_received()
+ <SubprocessProtocol.pipe_data_received>`
+ - Called when the child process writes data into its
+ *stdout* or *stderr* pipe.
+
+ * - ``callback`` :meth:`pipe_connection_lost()
+ <SubprocessProtocol.pipe_connection_lost>`
+ - Called when one of the pipes communicating with
+ the child process is closed.
+
+ * - ``callback`` :meth:`process_exited()
+ <SubprocessProtocol.process_exited>`
+ - Called when the child process has exited.
+
+
+Event Loop Policies
+===================
+
+Policies is a low-level mechanism to alter the behavior of
+functions like :func:`asyncio.get_event_loop`. See also
+the main :ref:`policies section <asyncio-policies>` for more
+details.
+
+
+.. rubric:: Accessing Policies
+.. list-table::
+ :widths: 50 50
+ :class: full-width-table
+
+ * - :meth:`asyncio.get_event_loop_policy`
+ - Return the current process-wide policy.
+
+ * - :meth:`asyncio.set_event_loop_policy`
+ - Set a new process-wide policy.
+
+ * - :class:`AbstractEventLoopPolicy`
+ - Base class for policy objects.