[pull] main from python:main

Doc/c-api/lifecycle.rst

@@ -19,7 +19,7 @@ object's life.  An arrow from *A* to *B* indicates that event *B* can occur
 after event *A* has occurred, with the arrow's label indicating the condition
 that must be true for *B* to occur after *A*.
 
-.. only:: html and not epub
+.. only:: builder_html
 
    .. raw:: html
 
@@ -50,20 +50,13 @@ that must be true for *B* to occur after *A*.
           })();
       </script>
 
-.. only:: epub or not (html or latex)
+.. only:: not builder_html
 
    .. image:: lifecycle.dot.svg
       :align: center
       :class: invert-in-dark-mode
       :alt: Diagram showing events in an object's life.  Explained in detail below.
 
-.. only:: latex
-
-   .. image:: lifecycle.dot.pdf
-      :align: center
-      :class: invert-in-dark-mode
-      :alt: Diagram showing events in an object's life.  Explained in detail below.
-
 .. container::
    :name: life-events-graph-description
 

Doc/library/http.server.rst

@@ -39,7 +39,17 @@ handler.  Code to create and run the server looks like this::
    This class builds on the :class:`~socketserver.TCPServer` class by storing
    the server address as instance variables named :attr:`server_name` and
    :attr:`server_port`. The server is accessible by the handler, typically
-   through the handler's :attr:`server` instance variable.
+   through the handler's :attr:`~socketserver.BaseRequestHandler.server`
+   instance variable.
+
+   .. attribute:: server_name
+
+      The HTTP server's fully qualified domain name.
+
+   .. attribute:: server_port
+
+      The HTTP server's port number obtained from *server_address*.
+
 
 .. class:: ThreadingHTTPServer(server_address, RequestHandlerClass)
 
@@ -60,7 +70,7 @@ handler.  Code to create and run the server looks like this::
    object fails with a :exc:`RuntimeError`.
 
    The *certfile* argument is the path to the SSL certificate chain file,
-   and the *keyfile* is the path to file containing the private key.
+   and the *keyfile* is the path to the file containing the private key.
 
    A *password* can be specified for files protected and wrapped with PKCS#8,
    but beware that this could possibly expose hardcoded passwords in clear.
@@ -140,7 +150,7 @@ instantiation, of which this module provides three different variants:
 
    .. attribute:: path
 
-      Contains the request path. If query component of the URL is present,
+      Contains the request path. If the query component of the URL is present,
       then ``path`` includes the query. Using the terminology of :rfc:`3986`,
       ``path`` here includes ``hier-part`` and the ``query``.
 
@@ -190,7 +200,7 @@ instantiation, of which this module provides three different variants:
       Specifies a format string that should be used by :meth:`send_error` method
       for building an error response to the client. The string is filled by
       default with variables from :attr:`responses` based on the status code
-      that passed to :meth:`send_error`.
+      passed to :meth:`send_error`.
 
    .. attribute:: error_content_type
 
@@ -238,8 +248,8 @@ instantiation, of which this module provides three different variants:
    .. method:: handle_expect_100()
 
       When an HTTP/1.1 conformant server receives an ``Expect: 100-continue``
-      request header it responds back with a ``100 Continue`` followed by ``200
-      OK`` headers.
+      request header it responds with a ``100 Continue`` followed by ``200 OK``
+      headers.
       This method can be overridden to raise an error if the server does not
       want the client to continue.  For example, the server can choose to send ``417
       Expectation Failed`` as a response header and ``return False``.
@@ -295,8 +305,8 @@ instantiation, of which this module provides three different variants:
    .. method:: send_response_only(code, message=None)
 
       Sends the response header only, used for the purposes when ``100
-      Continue`` response is sent by the server to the client. The headers not
-      buffered and sent directly the output stream.If the *message* is not
+      Continue`` response is sent by the server to the client. The headers are
+      not buffered and sent directly the output stream. If the *message* is not
       specified, the HTTP message corresponding the response *code*  is sent.
 
       This method does not reject *message* containing CRLF sequences.
@@ -338,7 +348,7 @@ instantiation, of which this module provides three different variants:
       to create custom error logging mechanisms. The *format* argument is a
       standard printf-style format string, where the additional arguments to
       :meth:`log_message` are applied as inputs to the formatting. The client
-      ip address and current date and time are prefixed to every message logged.
+      IP address and current date and time are prefixed to every message logged.
 
    .. method:: version_string()
 
@@ -402,6 +412,14 @@ instantiation, of which this module provides three different variants:
 
       .. versionadded:: 3.15
 
+   .. attribute:: index_pages
+
+      Specifies the filenames that are treated as directory index pages.
+
+      Defaults to ``("index.html", "index.htm")``.
+
+      .. versionadded:: 3.12
+
    .. attribute:: extensions_map
 
       A dictionary mapping suffixes into MIME types, contains custom overrides
@@ -434,8 +452,8 @@ instantiation, of which this module provides three different variants:
       The request is mapped to a local file by interpreting the request as a
       path relative to the current working directory.
 
-      If the request was mapped to a directory, the directory is checked for a
-      file named ``index.html`` or ``index.htm`` (in that order). If found, the
+      If the request was mapped to a directory, the directory is checked for
+      an index page as specified by :attr:`index_pages`. If found, the
       file's contents are returned; otherwise a directory listing is generated
       by calling the :meth:`list_directory` method. This method uses
       :func:`os.listdir` to scan the directory, and returns a ``404`` error
@@ -465,9 +483,32 @@ instantiation, of which this module provides three different variants:
       .. versionchanged:: 3.7
          Support of the ``'If-Modified-Since'`` header.
 
-The :class:`SimpleHTTPRequestHandler` class can be used in the following
-manner in order to create a very basic webserver serving files relative to
-the current directory::
+   .. method:: list_directory(path)
+
+      Helper to list the contents of *path* when no index page is present.
+
+      This returns either a :term:`file-like object` (which must be closed
+      by the caller) or ``None`` to indicate an error, in which case the
+      caller has nothing further to do. In either case, the headers are sent.
+
+   .. method:: guess_type(path)
+
+      Guess the type of the file at the given *path*.
+
+      This returns a string of the form ``type/subtype``, usable for
+      a MIME Content-type header.
+
+      The default implementation looks the file's extension up in
+      :attr:`extensions_map`, falling back to
+      :func:`mimetypes.guess_file_type` and then to
+      :attr:`default_content_type`.
+
+      .. versionchanged:: 3.13
+         Add :func:`mimetypes.guess_file_type` as a fallback.
+
+
+The :class:`SimpleHTTPRequestHandler` class can be used to create a very basic
+webserver serving files relative to the current directory as follows::
 
    import http.server
    import socketserver
@@ -483,7 +524,7 @@ the current directory::
 
 :class:`SimpleHTTPRequestHandler` can also be subclassed to enhance behavior,
 such as using different index file names by overriding the class attribute
-:attr:`index_pages`.
+:attr:`~SimpleHTTPRequestHandler.index_pages`.
 
 
 .. _http-server-cli:
@@ -599,8 +640,8 @@ The following options are accepted:
 
 .. option:: -H, --header <header> <value>
 
-   Specify an additional extra HTTP Response Header to send on successful HTTP
-   200 responses. Can be used multiple times to send additional custom response
+   Specify an additional HTTP Response Header to send on successful HTTP 200
+   responses. Can be used multiple times to send additional custom response
    headers. Headers that are sent automatically by the server (for instance
    Content-Type) will not be overwritten by the server.
 
@@ -615,13 +656,13 @@ Security considerations
 .. index:: pair: http.server; security
 
 :class:`SimpleHTTPRequestHandler` will follow symbolic links when handling
-requests, this makes it possible for files outside of the specified directory
+requests which makes it possible for files outside of the specified directory
 to be served.
 
 Methods :meth:`BaseHTTPRequestHandler.send_header` and
 :meth:`BaseHTTPRequestHandler.send_response_only` assume sanitized input
 and do not perform input validation such as checking for the presence of CRLF
-sequences. Untrusted input may result in HTTP Header injection attacks.
+sequences. Untrusted input may result in HTTP header injection attacks.
 
 Earlier versions of Python did not scrub control characters from the
 log messages emitted to stderr from ``python -m http.server`` or the

Doc/library/imaplib.rst

@@ -186,6 +186,9 @@ enclosed with either parentheses or double quotes) each string is quoted.
 However, the *password* argument to the ``LOGIN`` command is always quoted. If
 you want to avoid having an argument string quoted (eg: the *flags* argument to
 ``STORE``) then enclose the string in parentheses (eg: ``r'(\Deleted)'``).
+In general, pass arguments unquoted and let the module quote them as needed.
+An argument that is already enclosed in double quotes is left unchanged,
+so that code which quotes arguments itself keeps working.
 
 Most commands return a tuple: ``(type, [data, ...])`` where *type* is usually
 ``'OK'`` or ``'NO'``, and *data* is either the text from the command response,
@@ -410,7 +413,7 @@ An :class:`IMAP4` instance has the following methods:
    .. versionadded:: 3.14
 
 
-.. method:: IMAP4.list([directory[, pattern]])
+.. method:: IMAP4.list(directory='', pattern='*')
 
    List mailbox names in *directory* matching *pattern*.  *directory* defaults to
    the top-level mail folder, and *pattern* defaults to match anything.  Returned
@@ -440,7 +443,7 @@ An :class:`IMAP4` instance has the following methods:
       The method no longer ignores silently arbitrary exceptions.
 
 
-.. method:: IMAP4.lsub(directory='""', pattern='*')
+.. method:: IMAP4.lsub(directory='', pattern='*')
 
    List subscribed mailbox names in directory matching pattern. *directory*
    defaults to the top level directory and *pattern* defaults to match any mailbox.

Doc/library/re.rst

@@ -531,8 +531,9 @@ The special characters are:
    *name* exists, and with ``no-pattern`` if it doesn't. ``no-pattern`` is
    optional and can be omitted. For example,
    ``(<)?(\w+@\w+(?:\.\w+)+)(?(1)>|$)`` is a poor email matching pattern, which
-   will match with ``'<user@host.com>'`` as well as ``'user@host.com'``, but
-   not with ``'<user@host.com'`` nor ``'user@host.com>'``.
+   matches ``'<user@host.com>'`` as well as ``'user@host.com'``, but does not
+   match ``'<user@host.com'`` nor ``'user@host.com>'`` in their entirety
+   (:func:`re.search` finds only ``'user@host.com'`` in the former).
 
    .. versionchanged:: 3.12
       Group *id* can only contain ASCII digits.

Doc/library/tkinter.rst

@@ -656,6 +656,9 @@ method on it, and to change its value you call the :meth:`!set` method.
 If you follow this protocol, the widget will always track the value of the
 variable, with no further intervention on your part.
 
+Keep a reference to the variable for as long as a widget uses it, for example
+by storing it as an attribute (see :class:`Variable`).
+
 For example::
 
    import tkinter as tk
@@ -734,6 +737,8 @@ Here are some examples of typical usage::
    myapp.mainloop()
 
 
+.. _Tk-option-data-types:
+
 Tk option data types
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -767,12 +772,16 @@ color
    represent any legal hex digit.  See page 160 of Ousterhout's book for details.
 
 cursor
-   The standard X cursor names from :file:`cursorfont.h` can be used, without the
-   ``XC_`` prefix.  For example to get a hand cursor (``XC_hand2``), use the
-   string ``"hand2"``.  You can also specify a bitmap and mask file of your own.
+   The name of the mouse cursor to display while the pointer is over the widget.
+   Tk provides a portable set of cursor names available on all platforms
+   (for example ``"arrow"``, ``"watch"``, ``"cross"``, or ``"hand2"``);
+   the standard X cursor names from :file:`cursorfont.h` may also be used,
+   without the ``XC_`` prefix (so ``XC_hand2`` becomes ``"hand2"``).
+   The full list of names, including the platform-specific ones,
+   is given in the :manpage:`cursors(3tk)` manual page.
+   You can also specify a bitmap and mask file of your own.
    On Windows a cursor file (:file:`.cur` or :file:`.ani`) may be used directly,
    giving its path preceded with an ``@``, as in ``"@C:/cursors/bart.ani"``.
-   See page 179 of Ousterhout's book.
 
 distance
    Screen distances can be specified in either pixels or absolute distances.
@@ -2071,6 +2080,7 @@ Base and mixin classes
 
       Return the geometry of the widget, in the form ``widthxheight+x+y``.
       All dimensions are in pixels.
+      An offset can be negative; see :meth:`~Wm.geometry`.
 
    .. method:: winfo_height()
 
@@ -2541,6 +2551,8 @@ Base and mixin classes
       *width* and *height* are in pixels (or grid units for a gridded window);
       a position preceded by ``+`` is measured from the left or top edge of the
       screen and one preceded by ``-`` from the right or bottom edge.
+      An offset can be negative, as in ``'200x100+-9+-8'``, when the window
+      edge is positioned beyond the corresponding screen edge.
       An empty string cancels any user-specified geometry, letting the window
       revert to its natural size.
       With no argument, return the current geometry as a string of the form
@@ -5916,6 +5928,14 @@ Variable classes
    :class:`StringVar`, :class:`IntVar`, :class:`DoubleVar` or
    :class:`BooleanVar` -- rather than :class:`!Variable` directly.
 
+   .. note::
+
+      When a :class:`!Variable` is garbage collected, its Tcl variable is unset.
+      Keep a reference to it for as long as a widget is linked to it, for example
+      by storing it as an attribute rather than in a local variable.
+      Otherwise Tk recreates the Tcl variable to keep the widget working, but it
+      is never unset again, leaking one Tcl variable per dropped wrapper.
+
    .. versionchanged:: 3.10
       Two variables now compare equal (``==``) only when they have the same
       name, are of the same class, and belong to the same Tcl interpreter.

Doc/library/tkinter.ttk.rst

@@ -116,9 +116,10 @@ All the :mod:`!ttk` Widgets accept the following options:
 |           | read-only, and may only be specified when the window is      |
 |           | created.                                                     |
 +-----------+--------------------------------------------------------------+
-| cursor    | Specifies the mouse cursor to be used for the widget. If set |
-|           | to the empty string (the default), the cursor is inherited   |
-|           | from the parent widget.                                      |
+| cursor    | Specifies the mouse cursor to be used for the widget.  See   |
+|           | the *cursor* option type under :ref:`Tk-option-data-types`.  |
+|           | If set to the empty string (the default), the cursor is      |
+|           | inherited from the parent widget.                            |
 +-----------+--------------------------------------------------------------+
 | takefocus | Determines whether the window accepts the focus during       |
 |           | keyboard traversal. 0, 1 or an empty string is returned.     |

Doc/library/turtle.rst

@@ -46,7 +46,7 @@ direction it is facing, drawing a line as it moves.  Give it the command
    Turtle can draw intricate shapes using programs that repeat simple
    moves.
 
-   .. image:: turtle-star.*
+   .. image:: turtle-star.png
       :align: center
 
 In Python, turtle graphics provides a representation of a physical "turtle"

Doc/reference/compound_stmts.rst

@@ -279,12 +279,12 @@ and the exception occurs in the :keyword:`!try` clause of the inner handler,
 the outer handler will not handle the exception.)
 
 When an exception has been assigned using ``as target``, it is cleared at the
-end of the :keyword:`!except` clause.  This is as if ::
+end of the :keyword:`!except` clause.  This is as if::
 
    except E as N:
        foo
 
-was translated to ::
+was translated to::
 
    except E as N:
        try:
@@ -341,7 +341,7 @@ can have either :keyword:`except` or :keyword:`!except*` clauses, but not both.
 The exception type for matching is mandatory in the case of :keyword:`!except*`,
 so ``except*:`` is a syntax error. The type is interpreted as in the case of
 :keyword:`!except`, but matching is performed on the exceptions contained in the
-group that is being handled. An :exc:`TypeError` is raised if a matching
+group that is being handled. A :exc:`TypeError` is raised if a matching
 type is a subclass of :exc:`!BaseExceptionGroup`, because that would have
 ambiguous semantics.
 
@@ -357,7 +357,7 @@ or the last :keyword:`!except*` clause has run.
 
 After all :keyword:`!except*` clauses execute, the group of unhandled exceptions
 is merged with any exceptions that were raised or re-raised from within
-:keyword:`!except*` clauses. This merged exception group propagates on.::
+:keyword:`!except*` clauses. This merged exception group propagates on::
 
    >>> try:
    ...     raise ExceptionGroup("eg",
@@ -1311,7 +1311,7 @@ mutable object, such as a list or a dictionary: if the function modifies the
 object (e.g. by appending an item to a list), the default parameter value is in effect
 modified.  This is generally not what was intended.  A way around this is to use
 ``None`` as the default, and explicitly test for it in the body of the function,
-e.g.::
+for example::
 
    def whats_on_the_telly(penguin=None):
        if penguin is None:

Doc/tools/.nitignore

@@ -9,7 +9,6 @@ Doc/library/ast.rst
 Doc/library/asyncio-extending.rst
 Doc/library/email.charset.rst
 Doc/library/email.parser.rst
-Doc/library/http.server.rst
 Doc/library/importlib.rst
 Doc/library/logging.config.rst
 Doc/library/logging.handlers.rst