[pull] main from python:main

Doc/library/argparse.rst

@@ -442,9 +442,8 @@ is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
 
 .. note::
 
-   Empty lines are treated as empty strings (``''``), which are allowed as values but
-   not as arguments. Empty lines that are read as arguments will result in an
-   "unrecognized arguments" error.
+   Each line is treated as a single argument, so an empty line is read as an
+   empty string (``''``).
 
 :class:`ArgumentParser` uses :term:`filesystem encoding and error handler`
 to read the file containing arguments.
@@ -1052,6 +1051,10 @@ is used when no command-line argument was present::
    >>> parser.parse_args([])
    Namespace(foo=42)
 
+Because ``nargs='*'`` gathers any supplied values into a list, an absent
+positional argument yields an empty list (``[]``). Only a non-``None``
+*default* overrides this (so ``default=None`` still gives ``[]``).
+
 For required_ arguments, the ``default`` value is ignored. For example, this
 applies to positional arguments with nargs_ values other than ``?`` or ``*``,
 or optional arguments marked as ``required=True``.
@@ -1369,6 +1372,11 @@ behavior::
    >>> parser.parse_args('--foo XXX'.split())
    Namespace(bar='XXX')
 
+Multiple arguments may share the same ``dest``.  By default, the value from the
+last such argument given on the command line wins.  Use ``action='append'`` to
+collect values from all of them into a list instead.  For conflicting *option
+strings* rather than ``dest`` names, see conflict_handler_.
+
 .. versionchanged:: 3.15
    Single-dash long option now takes precedence over short options.
 
@@ -1777,6 +1785,11 @@ Subcommands
    present, and when the ``b`` command is specified, only the ``foo`` and
    ``baz`` attributes are present.
 
+   If a subparser defines an argument with the same ``dest`` as the parent
+   parser, the two share a single namespace attribute, so the parent's value
+   won't be retained. Users should give them  distinct ``dest`` values to
+   keep both.
+
    Similarly, when a help message is requested from a subparser, only the help
    for that particular parser will be printed.  The help message will not
    include parent parser or sibling parser messages.  (A help message for each
@@ -2232,6 +2245,9 @@ Customizing file parsing
         def convert_arg_line_to_args(self, arg_line):
             return arg_line.split()
 
+   Note that with this override an argument can no longer contain spaces, since
+   each space-separated word becomes a separate argument.
+
 
 Exiting methods
 ^^^^^^^^^^^^^^^

Doc/library/getpass.rst

@@ -18,7 +18,7 @@ The :mod:`!getpass` module provides two functions:
    the string *prompt*, which defaults to ``'Password: '``.  On Unix, the
    prompt is written to the file-like object *stream* using the replace error
    handler if needed.  *stream* defaults to the controlling terminal
-   (:file:`/dev/tty`) or if that is unavailable to ``sys.stderr`` (this
+   (:file:`/dev/tty`) or if that is unavailable to :data:`sys.stderr` (this
    argument is ignored on Windows).
 
    The *echo_char* argument controls how user input is displayed while typing.
@@ -27,12 +27,12 @@ The :mod:`!getpass` module provides two functions:
    typed character is replaced by it. For example, ``echo_char='*'`` will
    display asterisks instead of the actual input.
 
-   If echo free input is unavailable getpass() falls back to printing
-   a warning message to *stream* and reading from ``sys.stdin`` and
+   If echo-free input is unavailable, :func:`getpass` falls back to printing
+   a warning message to *stream* and reading from :data:`sys.stdin` and
    issuing a :exc:`GetPassWarning`.
 
    .. note::
-      If you call getpass from within IDLE, the input may be done in the
+      If you call :func:`getpass` from within IDLE, the input may be done in the
       terminal you launched IDLE from rather than the idle window itself.
 
    .. note::

Doc/library/ssl.rst

@@ -146,9 +146,9 @@ purposes.
    *cadata* is given) or uses :meth:`SSLContext.load_default_certs` to load
    default CA certificates.
 
-   When :attr:`~SSLContext.keylog_filename` is supported and the environment
-   variable :envvar:`SSLKEYLOGFILE` is set, :func:`create_default_context`
-   enables key logging.
+   When the environment variable :envvar:`!SSLKEYLOGFILE` is set,
+   :func:`create_default_context` enables key logging by setting
+   :attr:`~SSLContext.keylog_filename` to the variable's value.
 
    The default settings for this context include
    :data:`VERIFY_X509_PARTIAL_CHAIN` and :data:`VERIFY_X509_STRICT`.

Doc/tools/extensions/profiling_trace.py

@@ -154,10 +154,15 @@ def inject_trace(app, exception):
         )
 
 
+def add_assets(app, pagename, templatename, context, doctree):
+    if pagename == 'library/profiling.sampling':
+        app.add_js_file('profiling-sampling-visualization.js')
+        app.add_css_file('profiling-sampling-visualization.css')
+
+
 def setup(app):
     app.connect('build-finished', inject_trace)
-    app.add_js_file('profiling-sampling-visualization.js')
-    app.add_css_file('profiling-sampling-visualization.css')
+    app.connect('html-page-context', add_assets)
 
     return {
         'version': '1.0',

Lib/asyncio/base_events.py

@@ -488,10 +488,10 @@ def set_task_factory(self, factory):
         If factory is None the default task factory will be set.
 
         If factory is a callable, it should have a signature matching
-        '(loop, coro, **kwargs)', where 'loop' will be a reference to the active
-        event loop, 'coro' will be a coroutine object, and **kwargs will be
-        arbitrary keyword arguments that should be passed on to Task.
-        The callable must return a Task.
+        '(loop, coro, **kwargs)', where 'loop' will be a reference to the
+        active event loop, 'coro' will be a coroutine object, and **kwargs
+        will be arbitrary keyword arguments that should be passed on to
+        Task.  The callable must return a Task.
         """
         if factory is not None and not callable(factory):
             raise TypeError('task factory must be a callable or None')
@@ -727,8 +727,8 @@ def run_until_complete(self, future):
     def stop(self):
         """Stop running the event loop.
 
-        Every callback already scheduled will still run.  This simply informs
-        run_forever to stop looping after a complete iteration.
+        Every callback already scheduled will still run.  This simply
+        informs run_forever to stop looping after a complete iteration.
         """
         self._stopping = True
 
@@ -1076,12 +1076,12 @@ async def create_connection(
 
         Create a streaming transport connection to a given internet host and
         port: socket family AF_INET or socket.AF_INET6 depending on host (or
-        family if specified), socket type SOCK_STREAM. protocol_factory must be
-        a callable returning a protocol instance.
+        family if specified), socket type SOCK_STREAM. protocol_factory must
+        be a callable returning a protocol instance.
 
-        This method is a coroutine which will try to establish the connection
-        in the background.  When successful, the coroutine returns a
-        (transport, protocol) pair.
+        This method is a coroutine which will try to establish the
+        connection in the background.  When successful, the coroutine
+        returns a (transport, protocol) pair.
         """
         if server_hostname is not None and not ssl:
             raise ValueError('server_hostname is only meaningful with ssl')
@@ -1550,11 +1550,11 @@ async def create_server(
         The host parameter can be a string, in that case the TCP server is
         bound to host and port.
 
-        The host parameter can also be a sequence of strings and in that case
-        the TCP server is bound to all hosts of the sequence. If a host
-        appears multiple times (possibly indirectly e.g. when hostnames
-        resolve to the same IP address), the server is only bound once to that
-        host.
+        The host parameter can also be a sequence of strings and in that
+        case the TCP server is bound to all hosts of the sequence.  If
+        a host appears multiple times (possibly indirectly e.g. when
+        hostnames resolve to the same IP address), the server is only bound
+        once to that host.
 
         Return a Server object which can be used to stop the service.
 

Lib/asyncio/events.py

@@ -374,8 +374,8 @@ async def create_server(
 
         If host is an empty string or None all interfaces are assumed
         and a list of multiple sockets will be returned (most likely
-        one for IPv4 and another one for IPv6). The host parameter can also be
-        a sequence (e.g. list) of hosts to bind to.
+        one for IPv4 and another one for IPv6). The host parameter can also
+        be a sequence (e.g. list) of hosts to bind to.
 
         family can be set to either AF_INET or AF_INET6 to force the
         socket to use IPv4 or IPv6. If not set it will be determined
@@ -415,8 +415,9 @@ async def create_server(
 
         start_serving set to True (default) causes the created server
         to start accepting connections immediately.  When set to False,
-        the user should await Server.start_serving() or Server.serve_forever()
-        to make the server to start accepting connections.
+        the user should await Server.start_serving() or
+        Server.serve_forever() to make the server to start accepting
+        connections.
         """
         raise NotImplementedError
 
@@ -479,8 +480,9 @@ async def create_unix_server(
 
         start_serving set to True (default) causes the created server
         to start accepting connections immediately.  When set to False,
-        the user should await Server.start_serving() or Server.serve_forever()
-        to make the server to start accepting connections.
+        the user should await Server.start_serving() or
+        Server.serve_forever() to make the server to start accepting
+        connections.
         """
         raise NotImplementedError
 
@@ -511,8 +513,8 @@ async def create_datagram_endpoint(self, protocol_factory,
 
         protocol_factory must be a callable returning a protocol instance.
 
-        socket family AF_INET, socket.AF_INET6 or socket.AF_UNIX depending on
-        host (or family if specified), socket type SOCK_DGRAM.
+        socket family AF_INET, socket.AF_INET6 or socket.AF_UNIX depending
+        on host (or family if specified), socket type SOCK_DGRAM.
 
         reuse_address tells the kernel to reuse a local socket in
         TIME_WAIT state, without waiting for its natural timeout to
@@ -552,7 +554,8 @@ async def connect_read_pipe(self, protocol_factory, pipe):
     async def connect_write_pipe(self, protocol_factory, pipe):
         """Register write pipe in event loop.
 
-        protocol_factory should instantiate object with BaseProtocol interface.
+        protocol_factory should instantiate object with BaseProtocol
+        interface.
         Pipe is file-like object already switched to nonblocking.
         Return pair (transport, protocol), where transport support
         WriteTransport interface."""

Lib/asyncio/graph.py

@@ -112,13 +112,13 @@ def capture_call_graph(
     optional keyword-only 'depth' argument can be used to skip the specified
     number of frames from top of the stack.
 
-    If the optional keyword-only 'limit' argument is provided, each call stack
-    in the resulting graph is truncated to include at most ``abs(limit)``
-    entries. If 'limit' is positive, the entries left are the closest to
-    the invocation point. If 'limit' is negative, the topmost entries are
-    left. If 'limit' is omitted or None, all entries are present.
-    If 'limit' is 0, the call stack is not captured at all, only
-    "awaited by" information is present.
+    If the optional keyword-only 'limit' argument is provided, each call
+    stack in the resulting graph is truncated to include at most
+    ``abs(limit)`` entries.  If 'limit' is positive, the entries left are
+    the closest to the invocation point.  If 'limit' is negative, the
+    topmost entries are left.  If 'limit' is omitted or None, all entries
+    are present.  If 'limit' is 0, the call stack is not captured at all,
+    only "awaited by" information is present.
     """
 
     loop = events._get_running_loop()

Lib/asyncio/locks.py

@@ -155,10 +155,10 @@ def _wake_up_first(self):
 class Event(mixins._LoopBoundMixin):
     """Asynchronous equivalent to threading.Event.
 
-    Class implementing event objects. An event manages a flag that can be set
-    to true with the set() method and reset to false with the clear() method.
-    The wait() method blocks until the flag is true. The flag is initially
-    false.
+    Class implementing event objects.  An event manages a flag that can be
+    set to true with the set() method and reset to false with the clear()
+    method.  The wait() method blocks until the flag is true.  The flag is
+    initially false.
     """
 
     def __init__(self):
@@ -350,9 +350,9 @@ class Semaphore(_ContextManagerMixin, mixins._LoopBoundMixin):
     """A Semaphore implementation.
 
     A semaphore manages an internal counter which is decremented by each
-    acquire() call and incremented by each release() call. The counter
-    can never go below zero; when acquire() finds that it is zero, it blocks,
-    waiting until some other thread calls release().
+    acquire() call and incremented by each release() call.  The counter
+    can never go below zero; when acquire() finds that it is zero, it
+    blocks, waiting until some other thread calls release().
 
     Semaphores also support the context management protocol.
 
@@ -508,8 +508,8 @@ async def __aexit__(self, *args):
     async def wait(self):
         """Wait for the barrier.
 
-        When the specified number of tasks have started waiting, they are all
-        simultaneously awoken.
+        When the specified number of tasks have started waiting, they are
+        all simultaneously awoken.
         Returns an unique and individual index number from 0 to 'parties-1'.
         """
         async with self._cond:

Lib/asyncio/queues.py

@@ -33,9 +33,9 @@ class QueueShutDown(Exception):
 class Queue(mixins._LoopBoundMixin):
     """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 "await put()" will block when the
-    queue reaches maxsize, until an item is removed by get().
+    If maxsize is less than or equal to zero, the queue size is infinite.
+    If it is an integer greater than 0, then "await put()" will block when
+    the queue reaches maxsize, until an item is removed by get().
 
     Unlike queue.Queue, you can reliably know this Queue's size
     with qsize(), since your single-threaded asyncio application won't be
@@ -174,8 +174,8 @@ async def get(self):
 
         If queue is empty, wait until an item is available.
 
-        Raises QueueShutDown if the queue has been shut down and is empty, or
-        if the queue has been shut down immediately.
+        Raises QueueShutDown if the queue has been shut down and is empty,
+        or if the queue has been shut down immediately.
         """
         while self.empty():
             if self._is_shutdown and self.empty():
@@ -203,10 +203,11 @@ async def get(self):
     def get_nowait(self):
         """Remove and return an item from the queue.
 
-        Return an item if one is immediately available, else raise QueueEmpty.
+        Return an item if one is immediately available, else raise
+        QueueEmpty.
 
-        Raises QueueShutDown if the queue has been shut down and is empty, or
-        if the queue has been shut down immediately.
+        Raises QueueShutDown if the queue has been shut down and is empty,
+        or if the queue has been shut down immediately.
         """
         if self.empty():
             if self._is_shutdown:
@@ -223,12 +224,12 @@ def task_done(self):
         a subsequent call to task_done() tells the queue that the processing
         on the task is complete.
 
-        If a join() is currently blocking, it will resume when all items have
-        been processed (meaning that a task_done() call was received for every
-        item that had been put() into the queue).
+        If a join() is currently blocking, it will resume when all items
+        have been processed (meaning that a task_done() call was received
+        for every item that had been put() into the queue).
 
-        Raises ValueError if called more times than there were items placed in
-        the queue.
+        Raises ValueError if called more times than there were items placed
+        in the queue.
         """
         if self._unfinished_tasks <= 0:
             raise ValueError('task_done() called too many times')
@@ -239,10 +240,11 @@ def task_done(self):
     async def join(self):
         """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 calls 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, join() unblocks.
+        The count of unfinished tasks goes up whenever an item is added to
+        the queue.  The count goes down whenever a consumer calls
+        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,
+        join() unblocks.
         """
         if self._unfinished_tasks > 0:
             await self._finished.wait()

Lib/asyncio/runners.py

@@ -35,7 +35,8 @@ class Runner:
     with asyncio.Runner(debug=True) as runner:
         runner.run(main())
 
-    The run() method can be called multiple times within the runner's context.
+    The run() method can be called multiple times within the runner's
+    context.
 
     This can be useful for interactive console (e.g. IPython),
     unittest runners, console tools, -- everywhere when async code