diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/asyncio-dev.rst | 2 | ||||
| -rw-r--r-- | Doc/library/asyncio-eventloop.rst | 37 | ||||
| -rw-r--r-- | Doc/library/asyncio-protocol.rst | 2 | ||||
| -rw-r--r-- | Doc/library/asyncio-queue.rst | 169 | ||||
| -rw-r--r-- | Doc/library/asyncio-stream.rst | 20 | ||||
| -rw-r--r-- | Doc/library/asyncio-subprocess.rst | 17 | ||||
| -rw-r--r-- | Doc/library/asyncio-sync.rst | 192 | ||||
| -rw-r--r-- | Doc/library/asyncio-task.rst | 12 | ||||
| -rw-r--r-- | Doc/library/asyncio.rst | 6 | ||||
| -rw-r--r-- | Doc/library/binascii.rst | 6 | ||||
| -rw-r--r-- | Doc/library/copyreg.rst | 2 | ||||
| -rw-r--r-- | Doc/library/http.client.rst | 6 | ||||
| -rw-r--r-- | Doc/library/http.server.rst | 12 | ||||
| -rw-r--r-- | Doc/library/mimetypes.rst | 4 | ||||
| -rw-r--r-- | Doc/library/os.rst | 3 | ||||
| -rw-r--r-- | Doc/library/re.rst | 7 |
16 files changed, 285 insertions, 212 deletions
diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index bf77a8fb79..d7f474efae 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -212,6 +212,7 @@ Example of unhandled exception:: loop = asyncio.get_event_loop() asyncio.async(bug()) loop.run_forever() + loop.close() Output:: @@ -258,6 +259,7 @@ coroutine in another coroutine and use classic try/except:: loop = asyncio.get_event_loop() asyncio.async(handle_exception()) loop.run_forever() + loop.close() Another option is to use the :meth:`BaseEventLoop.run_until_complete` function:: diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 4f7fdfe60f..d27eb4bd82 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -22,6 +22,8 @@ It provides multiple facilities, amongst which: Base class of event loops. + This class is :ref:`not thread safe <asyncio-multithreading>`. + Run an event loop ----------------- @@ -104,6 +106,9 @@ keywords to your callback, use :func:`functools.partial`. For example, Like :meth:`call_soon`, but thread safe. + See the :ref:`concurrency and multithreading <asyncio-multithreading>` + section of the documentation. + .. _asyncio-delayed-calls: @@ -180,7 +185,7 @@ Coroutines Creating connections -------------------- -.. method:: 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:: 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) Create a streaming transport connection to a given Internet *host* and *port*: socket family :py:data:`~socket.AF_INET` or @@ -253,7 +258,7 @@ Creating connections (:class:`StreamReader`, :class:`StreamWriter`) instead of a protocol. -.. method:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0) +.. coroutinemethod:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0) Create datagram connection: socket family :py:data:`~socket.AF_INET` or :py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified), @@ -271,7 +276,7 @@ Creating connections :ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples. -.. method:: BaseEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None) +.. coroutinemethod:: BaseEventLoop.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 @@ -290,7 +295,7 @@ Creating connections Creating listening connections ------------------------------ -.. method:: 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) +.. 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) Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) bound to *host* and *port*. @@ -336,11 +341,13 @@ Creating listening connections :class:`StreamWriter`) pair and calls back a function with this pair. -.. method:: BaseEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None) +.. coroutinemethod:: BaseEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None) Similar to :meth:`BaseEventLoop.create_server`, but specific to the socket family :py:data:`~socket.AF_UNIX`. + This method is a :ref:`coroutine <coroutine>`. + Availability: UNIX. @@ -384,7 +391,7 @@ the file descriptor of a socket. Low-level socket operations --------------------------- -.. method:: BaseEventLoop.sock_recv(sock, nbytes) +.. coroutinemethod:: BaseEventLoop.sock_recv(sock, nbytes) Receive data from the socket. The return value is a bytes object representing the data received. The maximum amount of data to be received @@ -399,7 +406,7 @@ Low-level socket operations The :meth:`socket.socket.recv` method. -.. method:: BaseEventLoop.sock_sendall(sock, data) +.. coroutinemethod:: BaseEventLoop.sock_sendall(sock, data) Send data to the socket. The socket must be connected to a remote socket. This method continues to send data from *data* until either all data has @@ -416,7 +423,7 @@ Low-level socket operations The :meth:`socket.socket.sendall` method. -.. method:: BaseEventLoop.sock_connect(sock, address) +.. coroutinemethod:: BaseEventLoop.sock_connect(sock, address) Connect to a remote socket at *address*. @@ -438,7 +445,7 @@ Low-level socket operations method. -.. method:: BaseEventLoop.sock_accept(sock) +.. coroutinemethod:: BaseEventLoop.sock_accept(sock) Accept a connection. The socket must be bound to an address and listening for connections. The return value is a pair ``(conn, address)`` where *conn* @@ -459,12 +466,12 @@ Low-level socket operations Resolve host name ----------------- -.. method:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0) +.. coroutinemethod:: BaseEventLoop.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. -.. method:: BaseEventLoop.getnameinfo(sockaddr, flags=0) +.. coroutinemethod:: BaseEventLoop.getnameinfo(sockaddr, flags=0) This method is a :ref:`coroutine <coroutine>`, similar to :meth:`socket.getnameinfo` function but non-blocking. @@ -476,7 +483,7 @@ Connect pipes On Windows with :class:`SelectorEventLoop`, these methods are not supported. Use :class:`ProactorEventLoop` to support pipes on Windows. -.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe) +.. coroutinemethod:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe) Register read pipe in eventloop. @@ -490,7 +497,7 @@ Use :class:`ProactorEventLoop` to support pipes on Windows. This method is a :ref:`coroutine <coroutine>`. -.. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe) +.. coroutinemethod:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe) Register write pipe in eventloop. @@ -543,7 +550,7 @@ Call a function in an :class:`~concurrent.futures.Executor` (pool of threads or pool of processes). By default, an event loop uses a thread pool executor (:class:`~concurrent.futures.ThreadPoolExecutor`). -.. method:: BaseEventLoop.run_in_executor(executor, callback, \*args) +.. coroutinemethod:: BaseEventLoop.run_in_executor(executor, callback, \*args) Arrange for a callback to be called in the specified executor. @@ -654,7 +661,7 @@ Server The server is closed asynchonously, use the :meth:`wait_closed` coroutine to wait until the server is closed. - .. method:: wait_closed() + .. coroutinemethod:: wait_closed() Wait until the :meth:`close` method completes. diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst index b6fcc4840b..2e671e89a2 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -23,6 +23,8 @@ then call the transport's methods for various purposes. subprocess pipes. The methods available on a transport depend on the transport's kind. +The transport classes are :ref:`not thread safe <asyncio-multithreading>`. + BaseTransport ------------- diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst new file mode 100644 index 0000000000..c82e08b105 --- /dev/null +++ b/Doc/library/asyncio-queue.rst @@ -0,0 +1,169 @@ +.. currentmodule:: asyncio + +Queues +====== + +Queues: + +* :class:`Queue` +* :class:`PriorityQueue` +* :class:`LifoQueue` +* :class:`JoinableQueue` + +asyncio queue API was designed to be close to classes of the :mod:`queue` +module (:class:`~queue.Queue`, :class:`~queue.PriorityQueue`, +:class:`~queue.LifoQueue`), but it has no *timeout* parameter. The +:func:`asyncio.wait_for` function can be used to cancel a task after a timeout. + +Queue +----- + +.. class:: Queue(maxsize=0, \*, loop=None) + + A queue, useful for coordinating producer and consumer coroutines. + + If *maxsize* is less than or equal to zero, the queue size is infinite. If + it is an integer greater than ``0``, then ``yield from put()`` will block + when the queue reaches *maxsize*, until an item is removed by :meth:`get`. + + Unlike the standard library :mod:`queue`, you can reliably know this Queue's + size with :meth:`qsize`, since your single-threaded asyncio application won't + be interrupted between calling :meth:`qsize` and doing an operation on the + Queue. + + This class is :ref:`not thread safe <asyncio-multithreading>`. + + .. versionchanged:: 3.4.3 + New :meth:`join` and :meth:`task_done` methods. + + .. method:: empty() + + Return ``True`` if the queue is empty, ``False`` otherwise. + + .. method:: full() + + Return ``True`` if there are :attr:`maxsize` items in the queue. + + .. note:: + + If the Queue was initialized with ``maxsize=0`` (the default), then + :meth:`full()` is never ``True``. + + .. coroutinemethod:: get() + + Remove and return an item from the queue. If queue is empty, wait until + an item is available. + + This method is a :ref:`coroutine <coroutine>`. + + .. seealso:: + + The :meth:`empty` method. + + .. method:: get_nowait() + + Remove and return an item from the queue. + + Return an item if one is immediately available, else raise + :exc:`QueueEmpty`. + + .. coroutinemethod:: join() + + Block until all items in the queue have been gotten and processed. + + The count of unfinished tasks goes up whenever an item is added to the + queue. The count goes down whenever a consumer thread calls + :meth:`task_done` to indicate that the item was retrieved and all work on + it is complete. When the count of unfinished tasks drops to zero, + :meth:`join` unblocks. + + This method is a :ref:`coroutine <coroutine>`. + + .. versionadded:: 3.4.3 + + .. coroutinemethod:: put(item) + + Put an item into the queue. If the queue is full, wait until a free slot + is available before adding item. + + This method is a :ref:`coroutine <coroutine>`. + + .. seealso:: + + The :meth:`full` method. + + .. method:: put_nowait(item) + + Put an item into the queue without blocking. + + If no free slot is immediately available, raise :exc:`QueueFull`. + + .. method:: qsize() + + Number of items in the queue. + + .. method:: task_done() + + Indicate that a formerly enqueued task is complete. + + Used by queue consumers. For each :meth:`~Queue.get` used to fetch a task, a + subsequent call to :meth:`task_done` tells the queue that the processing + on the task is complete. + + If a :meth:`join` is currently blocking, it will resume when all items + have been processed (meaning that a :meth:`task_done` call was received + for every item that had been :meth:`~Queue.put` into the queue). + + Raises :exc:`ValueError` if called more times than there were items + placed in the queue. + + .. versionadded:: 3.4.3 + + .. attribute:: maxsize + + Number of items allowed in the queue. + + +PriorityQueue +------------- + +.. class:: PriorityQueue + + A subclass of :class:`Queue`; retrieves entries in priority order (lowest + first). + + Entries are typically tuples of the form: (priority number, data). + + +LifoQueue +--------- + +.. class:: LifoQueue + + A subclass of :class:`Queue` that retrieves most recently added entries + first. + + +JoinableQueue +^^^^^^^^^^^^^ + +.. class:: JoinableQueue + + Deprecated alias for :class:`Queue`. + + .. deprecated:: 3.4.3 + + +Exceptions +^^^^^^^^^^ + +.. exception:: QueueEmpty + + Exception raised when the :meth:`~Queue.get_nowait` method is called on a + :class:`Queue` object which is empty. + + +.. exception:: QueueFull + + Exception raised when the :meth:`~Queue.put_nowait` method is called on a + :class:`Queue` object which is full. diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 3809d947d5..41b24acaaf 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -9,7 +9,7 @@ Streams (high-level API) Stream functions ================ -.. function:: open_connection(host=None, port=None, \*, loop=None, limit=None, **kwds) +.. coroutinefunction:: open_connection(host=None, port=None, \*, loop=None, limit=None, \*\*kwds) A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader, writer) pair. @@ -32,7 +32,7 @@ Stream functions This function is a :ref:`coroutine <coroutine>`. -.. function:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, **kwds) +.. 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()`. @@ -56,7 +56,7 @@ Stream functions This function is a :ref:`coroutine <coroutine>`. -.. function:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds) +.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds) A wrapper for :meth:`~BaseEventLoop.create_unix_connection()` returning a (reader, writer) pair. @@ -68,7 +68,7 @@ Stream functions Availability: UNIX. -.. function:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, **kwds) +.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, **kwds) Start a UNIX Domain Socket server, with a callback for each client connected. @@ -85,6 +85,8 @@ StreamReader .. class:: StreamReader(limit=None, loop=None) + This class is :ref:`not thread safe <asyncio-multithreading>`. + .. method:: exception() Get the exception. @@ -106,7 +108,7 @@ StreamReader Set the transport. - .. method:: read(n=-1) + .. 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. @@ -116,7 +118,7 @@ StreamReader This method is a :ref:`coroutine <coroutine>`. - .. method:: readline() + .. coroutinemethod:: readline() Read one line, where "line" is a sequence of bytes ending with ``\n``. @@ -128,7 +130,7 @@ StreamReader This method is a :ref:`coroutine <coroutine>`. - .. method:: readexactly(n) + .. coroutinemethod:: readexactly(n) Read exactly *n* bytes. Raise an :exc:`IncompleteReadError` if the end of the stream is reached before *n* can be read, the @@ -155,6 +157,8 @@ StreamWriter wait for flow control. It also adds a transport attribute which references the :class:`Transport` directly. + This class is :ref:`not thread safe <asyncio-multithreading>`. + .. attribute:: transport Transport. @@ -168,7 +172,7 @@ StreamWriter Close the transport: see :meth:`BaseTransport.close`. - .. method:: drain() + .. coroutinemethod:: drain() Let the write buffer of the underlying transport a chance to be flushed. diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 570107e3e4..1b8203047a 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -27,7 +27,7 @@ Example to use it on Windows:: Create a subprocess: high-level API using Process ------------------------------------------------- -.. function:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds) +.. coroutinefunction:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds) Create a subprocess. @@ -39,7 +39,7 @@ Create a subprocess: high-level API using Process This function is a :ref:`coroutine <coroutine>`. -.. function:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds) +.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds) Run the shell command *cmd*. @@ -67,7 +67,7 @@ Create a subprocess: low-level API using subprocess.Popen Run subprocesses asynchronously using the :mod:`subprocess` module. -.. method:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs) +.. coroutinemethod:: BaseEventLoop.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 @@ -116,7 +116,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module. See the constructor of the :class:`subprocess.Popen` class for parameters. -.. method:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs) +.. coroutinemethod:: BaseEventLoop.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>`, @@ -193,7 +193,10 @@ Process :meth:`~subprocess.Popen.wait` method of the :class:`~subprocess.Popen` class is implemented as a busy loop. - .. method:: wait() + This class is :ref:`not thread safe <asyncio-multithreading>`. See also the + :ref:`Subprocess and threads <asyncio-subprocess-threads>` section. + + .. coroutinemethod:: wait() Wait for child process to terminate. Set and return :attr:`returncode` attribute. @@ -207,7 +210,7 @@ Process blocks waiting for the OS pipe buffer to accept more data. Use the :meth:`communicate` method when using pipes to avoid that. - .. method:: communicate(input=None) + .. coroutinemethod:: communicate(input=None) Interact with process: Send data to stdin. Read data from stdout and stderr, until end-of-file is reached. Wait for process to terminate. @@ -310,6 +313,8 @@ are limits: subprocesses from other threads. Call the :func:`get_child_watcher` function in the main thread to instantiate the child watcher. +The :class:`asyncio.subprocess.Process` class is not thread safe. + .. seealso:: The :ref:`Concurrency and multithreading in asyncio diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst index 80974d9ee1..622ff5fd66 100644 --- a/Doc/library/asyncio-sync.rst +++ b/Doc/library/asyncio-sync.rst @@ -9,22 +9,16 @@ Locks: * :class:`Lock` * :class:`Event` * :class:`Condition` -* :class:`Semaphore` -* :class:`BoundedSemaphore` -Queues: +Semaphores: -* :class:`Queue` -* :class:`PriorityQueue` -* :class:`LifoQueue` -* :class:`JoinableQueue` +* :class:`Semaphore` +* :class:`BoundedSemaphore` -asyncio locks and queues API were designed to be close to classes of the -:mod:`threading` module (:class:`~threading.Lock`, :class:`~threading.Event`, +asyncio lock API was designed to be close to classes of the :mod:`threading` +module (:class:`~threading.Lock`, :class:`~threading.Event`, :class:`~threading.Condition`, :class:`~threading.Semaphore`, -:class:`~threading.BoundedSemaphore`) and the :mod:`queue` module -(:class:`~queue.Queue`, :class:`~queue.PriorityQueue`, -:class:`~queue.LifoQueue`), but they have no *timeout* parameter. The +:class:`~threading.BoundedSemaphore`), but it has no *timeout* parameter. The :func:`asyncio.wait_for` function can be used to cancel a task after a timeout. Locks @@ -60,6 +54,8 @@ Lock Locks also support the context management protocol. ``(yield from lock)`` should be used as context manager expression. + This class is :ref:`not thread safe <asyncio-multithreading>`. + Usage:: lock = Lock() @@ -89,7 +85,7 @@ Lock Return ``True`` if the lock is acquired. - .. method:: acquire() + .. coroutinemethod:: acquire() Acquire a lock. @@ -123,6 +119,8 @@ Event method. The :meth:`wait` method blocks until the flag is true. The flag is initially false. + This class is :ref:`not thread safe <asyncio-multithreading>`. + .. method:: clear() Reset the internal flag to false. Subsequently, coroutines calling @@ -139,7 +137,7 @@ Event true are awakened. Coroutine that call :meth:`wait` once the flag is true will not block at all. - .. method:: wait() + .. coroutinemethod:: wait() Block until the internal flag is true. @@ -166,7 +164,9 @@ Condition object, and it is used as the underlying lock. Otherwise, a new :class:`Lock` object is created and used as the underlying lock. - .. method:: acquire() + This class is :ref:`not thread safe <asyncio-multithreading>`. + + .. coroutinemethod:: acquire() Acquire the underlying lock. @@ -213,7 +213,7 @@ Condition There is no return value. - .. method:: wait() + .. coroutinemethod:: wait() Wait until notified. @@ -227,7 +227,7 @@ Condition This method is a :ref:`coroutine <coroutine>`. - .. method:: wait_for(predicate) + .. coroutinemethod:: wait_for(predicate) Wait until a predicate becomes true. @@ -258,7 +258,9 @@ Semaphore defaults to ``1``. If the value given is less than ``0``, :exc:`ValueError` is raised. - .. method:: acquire() + This class is :ref:`not thread safe <asyncio-multithreading>`. + + .. coroutinemethod:: acquire() Acquire a semaphore. @@ -273,7 +275,7 @@ Semaphore Returns ``True`` if semaphore can not be acquired immediately. - .. method:: release() + .. coroutinemethod:: release() Release a semaphore, incrementing the internal counter by one. When it was zero on entry and another coroutine is waiting for it to become @@ -285,154 +287,8 @@ BoundedSemaphore .. class:: BoundedSemaphore(value=1, \*, loop=None) - A bounded semaphore implementation. Inherit from :class:`Semaphore`. - - This raises :exc:`ValueError` in :meth:`~Semaphore.release` if it would - increase the value above the initial value. - - -Queues ------- - -Queue -^^^^^ - -.. class:: Queue(maxsize=0, \*, loop=None) - - A queue, useful for coordinating producer and consumer coroutines. - - If *maxsize* is less than or equal to zero, the queue size is infinite. If - it is an integer greater than ``0``, then ``yield from put()`` will block - when the queue reaches *maxsize*, until an item is removed by :meth:`get`. - - Unlike the standard library :mod:`queue`, you can reliably know this Queue's - size with :meth:`qsize`, since your single-threaded asyncio application won't - be interrupted between calling :meth:`qsize` and doing an operation on the - Queue. - - .. method:: empty() - - Return ``True`` if the queue is empty, ``False`` otherwise. - - .. method:: full() - - Return ``True`` if there are :attr:`maxsize` items in the queue. - - .. note:: - - If the Queue was initialized with ``maxsize=0`` (the default), then - :meth:`full()` is never ``True``. - - .. method:: get() - - Remove and return an item from the queue. If queue is empty, wait until - an item is available. - - This method is a :ref:`coroutine <coroutine>`. - - .. seealso:: - - The :meth:`empty` method. - - .. method:: get_nowait() - - Remove and return an item from the queue. - - Return an item if one is immediately available, else raise - :exc:`QueueEmpty`. - - .. method:: put(item) - - Put an item into the queue. If the queue is full, wait until a free slot - is available before adding item. - - This method is a :ref:`coroutine <coroutine>`. - - .. seealso:: - - The :meth:`full` method. - - .. method:: put_nowait(item) - - Put an item into the queue without blocking. - - If no free slot is immediately available, raise :exc:`QueueFull`. - - .. method:: qsize() - - Number of items in the queue. - - .. attribute:: maxsize - - Number of items allowed in the queue. - - -PriorityQueue -^^^^^^^^^^^^^ - -.. class:: PriorityQueue - - A subclass of :class:`Queue`; retrieves entries in priority order (lowest - first). - - Entries are typically tuples of the form: (priority number, data). - - -LifoQueue -^^^^^^^^^ - -.. class:: LifoQueue - - A subclass of :class:`Queue` that retrieves most recently added entries - first. - - -JoinableQueue -^^^^^^^^^^^^^ - -.. class:: JoinableQueue - - A subclass of :class:`Queue` with :meth:`task_done` and :meth:`join` - methods. - - .. method:: join() - - Block until all items in the queue have been gotten and processed. - - The count of unfinished tasks goes up whenever an item is added to the - queue. The count goes down whenever a consumer thread calls - :meth:`task_done` to indicate that the item was retrieved and all work on - it is complete. When the count of unfinished tasks drops to zero, - :meth:`join` unblocks. - - This method is a :ref:`coroutine <coroutine>`. - - .. method:: task_done() - - Indicate that a formerly enqueued task is complete. - - Used by queue consumers. For each :meth:`~Queue.get` used to fetch a task, a - subsequent call to :meth:`task_done` tells the queue that the processing - on the task is complete. - - If a :meth:`join` is currently blocking, it will resume when all items - have been processed (meaning that a :meth:`task_done` call was received - for every item that had been :meth:`~Queue.put` into the queue). - - Raises :exc:`ValueError` if called more times than there were items - placed in the queue. - - -Exceptions -^^^^^^^^^^ - -.. exception:: QueueEmpty - - Exception raised when the :meth:`~Queue.get_nowait` method is called on a - :class:`Queue` object which is empty. - + A bounded semaphore implementation. Inherit from :class:`Semaphore`. -.. exception:: QueueFull + This raises :exc:`ValueError` in :meth:`~Semaphore.release` if it would + increase the value above the initial value. - Exception raised when the :meth:`~Queue.put_nowait` method is called on a - :class:`Queue` object which is full. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 3008c86709..158a0d8784 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -209,6 +209,8 @@ Future :func:`~concurrent.futures.as_completed` functions in the :mod:`concurrent.futures` package. + This class is :ref:`not thread safe <asyncio-multithreading>`. + .. method:: cancel() Cancel the future and schedule callbacks. @@ -375,6 +377,8 @@ Task Don't directly create :class:`Task` instances: use the :func:`async` function or the :meth:`BaseEventLoop.create_task` method. + This class is :ref:`not thread safe <asyncio-multithreading>`. + .. classmethod:: all_tasks(loop=None) Return a set of all tasks for an event loop. @@ -545,7 +549,7 @@ Task functions Return ``True`` if *func* is a decorated :ref:`coroutine function <coroutine>`. -.. function:: sleep(delay, result=None, \*, loop=None) +.. coroutinefunction:: sleep(delay, result=None, \*, loop=None) Create a :ref:`coroutine <coroutine>` that completes after a given time (in seconds). If *result* is provided, it is produced to the caller @@ -554,6 +558,8 @@ Task functions The resolution of the sleep depends on the :ref:`granularity of the event loop <asyncio-delayed-calls>`. + This function is a :ref:`coroutine <coroutine>`. + .. function:: shield(arg, \*, loop=None) Wait for a future, shielding it from cancellation. @@ -581,7 +587,7 @@ Task functions except CancelledError: res = None -.. function:: wait(futures, \*, loop=None, timeout=None, return_when=ALL_COMPLETED) +.. coroutinefunction:: wait(futures, \*, loop=None, timeout=None, return_when=ALL_COMPLETED) Wait for the Futures and coroutine objects given by the sequence *futures* to complete. Coroutines will be wrapped in Tasks. Returns two sets of @@ -626,7 +632,7 @@ Task functions when the timeout occurs are returned in the second set. -.. function:: wait_for(fut, timeout, \*, loop=None) +.. coroutinefunction:: wait_for(fut, timeout, \*, loop=None) Wait for the single :class:`Future` or :ref:`coroutine object <coroutine>` to complete with timeout. If *timeout* is ``None``, block until the future diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index 690019859b..9b4d65e5da 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -46,6 +46,11 @@ Here is a more detailed list of the package contents: you absolutely, positively have to use a library that makes blocking I/O calls. +Asynchronous programming is more complex than classical "sequential" +programming: see the :ref:`Develop with asyncio <asyncio-dev>` page which lists +common traps and explains how to avoid them. :ref:`Enable the debug mode +<asyncio-debug-mode>` during development to detect common issues. + Table of contents: .. toctree:: @@ -58,6 +63,7 @@ Table of contents: asyncio-stream.rst asyncio-subprocess.rst asyncio-sync.rst + asyncio-queue.rst asyncio-dev.rst .. seealso:: diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst index c92a8e160a..3f7df74de9 100644 --- a/Doc/library/binascii.rst +++ b/Doc/library/binascii.rst @@ -65,9 +65,6 @@ The :mod:`binascii` module defines the following functions: data. More than one line may be passed at a time. If the optional argument *header* is present and true, underscores will be decoded as spaces. - .. versionchanged:: 3.2 - Accept only bytestring or bytearray objects as input. - .. function:: b2a_qp(data, quotetabs=False, istext=True, header=False) @@ -156,9 +153,6 @@ The :mod:`binascii` module defines the following functions: of hexadecimal digits (which can be upper or lower case), otherwise a :exc:`TypeError` is raised. - .. versionchanged:: 3.2 - Accept only bytestring or bytearray objects as input. - .. exception:: Error diff --git a/Doc/library/copyreg.rst b/Doc/library/copyreg.rst index 50d5879ae5..18306c7f99 100644 --- a/Doc/library/copyreg.rst +++ b/Doc/library/copyreg.rst @@ -9,7 +9,7 @@ module: pickle module: copy -The :mod:`copyreg` module offers a way to define fuctions used while pickling +The :mod:`copyreg` module offers a way to define functions used while pickling specific objects. The :mod:`pickle` and :mod:`copy` modules use those functions when pickling/copying those objects. The module provides configuration information about object constructors which are not classes. diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index a3f2e355d5..b6e78b520e 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -169,6 +169,12 @@ The following exceptions are raised as appropriate: status code that we don't understand. +.. exception:: LineTooLong + + A subclass of :exc:`HTTPException`. Raised if an excessively long line + is received in the HTTP protocol from the server. + + The constants defined in this module are: .. data:: HTTP_PORT diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index 0d8e7fe6c7..a75015555d 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -64,6 +64,18 @@ of which this module provides three different variants: Contains the server instance. + .. attribute:: close_connection + + Boolean that should be set before :meth:`handle_one_request` returns, + indicating if another request may be expected, or if the connection should + be shut down. + + .. attribute:: requestline + + Contains the string representation of the HTTP request line. The + terminating CRLF is stripped. This attribute should be set by + :meth:`handle_one_request`. If no valid request line was processed, it + should be set to the empty string. .. attribute:: command diff --git a/Doc/library/mimetypes.rst b/Doc/library/mimetypes.rst index f836243e7a..8739ea3dcd 100644 --- a/Doc/library/mimetypes.rst +++ b/Doc/library/mimetypes.rst @@ -106,8 +106,8 @@ behavior of the module. extension is already known, the new type will replace the old one. When the type is already known the extension will be added to the list of known extensions. - When *strict* is ``True`` (the default), the mapping will added to the official MIME - types, otherwise to the non-standard ones. + When *strict* is ``True`` (the default), the mapping will be added to the + official MIME types, otherwise to the non-standard ones. .. data:: inited diff --git a/Doc/library/os.rst b/Doc/library/os.rst index f217a36f4d..98ee842126 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -2159,7 +2159,8 @@ features: contain :func:`os.access`, otherwise it will be empty. To check whether you can use the *effective_ids* parameter for - :func:`os.access`, use the ``in`` operator on ``supports_dir_fd``, like so:: + :func:`os.access`, use the ``in`` operator on ``supports_effective_ids``, + like so:: os.access in os.supports_effective_ids diff --git a/Doc/library/re.rst b/Doc/library/re.rst index dfc25ea089..c3c8b65d8d 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -281,7 +281,9 @@ The special characters are: assertion`. ``(?<=abc)def`` will find a match in ``abcdef``, since the lookbehind will back up 3 characters and check if the contained pattern matches. The contained pattern must only match strings of some fixed length, meaning that - ``abc`` or ``a|b`` are allowed, but ``a*`` and ``a{3,4}`` are not. Note that + ``abc`` or ``a|b`` are allowed, but ``a*`` and ``a{3,4}`` are not. Group + references are not supported even if they match strings of some fixed length. + Note that patterns which start with positive lookbehind assertions will not match at the beginning of the string being searched; you will most likely want to use the :func:`search` function rather than the :func:`match` function: @@ -301,7 +303,8 @@ The special characters are: Matches if the current position in the string is not preceded by a match for ``...``. This is called a :dfn:`negative lookbehind assertion`. Similar to positive lookbehind assertions, the contained pattern must only match strings of - some fixed length. Patterns which start with negative lookbehind assertions may + some fixed length and shouldn't contain group references. + Patterns which start with negative lookbehind assertions may match at the beginning of the string being searched. ``(?(id/name)yes-pattern|no-pattern)`` |