Deploy preview for PR 1231 🛫

Author: pydoc-zh-tw[bot]

pr-preview/pr-1231/_sources/c-api/lifecycle.rst.txt

@@ -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
 

pr-preview/pr-1231/_sources/library/http.server.rst.txt

@@ -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()
 
@@ -390,6 +400,14 @@ instantiation, of which this module provides three different variants:
       This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is
       defined at the module level.
 
+   .. 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
@@ -413,8 +431,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
@@ -441,9 +459,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
+      ``'application/octet-stream'``.
+
+      .. 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
@@ -459,7 +500,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`.
 
 
 .. class:: CGIHTTPRequestHandler(request, client_address, server)
@@ -480,7 +521,9 @@ such as using different index file names by overriding the class attribute
    the other common server configuration is to treat special extensions as
    denoting CGI scripts.
 
-   The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts
+   The :func:`~SimpleHTTPRequestHandler.do_GET` and
+   :func:`~SimpleHTTPRequestHandler.do_HEAD` functions
+   are modified to run CGI scripts
    and serve the output, instead of serving files, if the request leads to
    somewhere below the ``cgi_directories`` path.
 
@@ -637,13 +680,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

pr-preview/pr-1231/_sources/library/imaplib.rst.txt

@@ -24,7 +24,7 @@
 This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
 :class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and
 implement a large subset of the IMAP4rev1 client protocol as defined in
-:rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
+:rfc:`3501`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
 note that the ``STATUS`` command is not supported in IMAP4.
 
 .. include:: ../includes/wasm-notavail.rst
@@ -135,21 +135,23 @@ The second subclass allows for connections created by a child process:
 The following utility functions are defined:
 
 
-.. function:: Internaldate2tuple(datestr)
+.. function:: Internaldate2tuple(resp)
 
-   Parse an IMAP4 ``INTERNALDATE`` string and return corresponding local
-   time.  The return value is a :class:`time.struct_time` tuple or
-   ``None`` if the string has wrong format.
+   Parse a :term:`bytes-like object` containing an IMAP4 ``INTERNALDATE``
+   response and return the corresponding local time.  The return value is a
+   :class:`time.struct_time` tuple or ``None`` if the input has wrong format.
 
 .. function:: Int2AP(num)
 
    Converts an integer into a bytes representation using characters from the set
    [``A`` .. ``P``].
 
 
-.. function:: ParseFlags(flagstr)
+.. function:: ParseFlags(resp)
 
-   Converts an IMAP4 ``FLAGS`` response to a tuple of individual flags.
+   Converts a :term:`bytes-like object` containing an IMAP4 ``FLAGS`` response
+   to a tuple of individual flags as :class:`bytes`.  The return value is an
+   empty tuple if the input has wrong format.
 
 
 .. function:: Time2Internaldate(date_time)
@@ -194,6 +196,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,
@@ -214,6 +219,11 @@ An :class:`IMAP4` instance has the following methods:
 
    Append *message* to named mailbox.
 
+   *flags* may be ``None`` or a string of IMAP flag tokens.  Multiple
+   flags are separated by spaces, for example ``r'\Seen \Answered'``.
+   If *flags* is not already enclosed in parentheses, parentheses are
+   added automatically.
+
 
 .. method:: IMAP4.authenticate(mechanism, authobject)
 
@@ -402,7 +412,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
@@ -432,7 +442,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.
@@ -619,7 +629,7 @@ An :class:`IMAP4` instance has the following methods:
 .. method:: IMAP4.store(message_set, command, flag_list)
 
    Alters flag dispositions for messages in mailbox.  *command* is specified by
-   section 6.4.6 of :rfc:`2060` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
+   section 6.4.6 of :rfc:`3501` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
    optionally with a suffix of ".SILENT".
 
    For example, to set the delete flag on all messages::
@@ -633,11 +643,11 @@ An :class:`IMAP4` instance has the following methods:
 
       Creating flags containing ']' (for example: "[test]") violates
       :rfc:`3501` (the IMAP protocol).  However, imaplib has historically
-      allowed creation of such tags, and popular IMAP servers, such as Gmail,
+      allowed creation of such flags, and popular IMAP servers, such as Gmail,
       accept and produce such flags.  There are non-Python programs which also
-      create such tags.  Although it is an RFC violation and IMAP clients and
+      create such flags.  Although it is an RFC violation and IMAP clients and
       servers are supposed to be strict, imaplib still continues to allow
-      such tags to be created for backward compatibility reasons, and as of
+      such flags to be created for backward compatibility reasons, and as of
       Python 3.6, handles them if they are sent from the server, since this
       improves real-world compatibility.
 

pr-preview/pr-1231/_sources/library/re.rst.txt

@@ -512,8 +512,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.

pr-preview/pr-1231/_sources/library/tkinter.rst.txt

@@ -658,6 +658,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
@@ -736,6 +739,8 @@ Here are some examples of typical usage::
    myapp.mainloop()
 
 
+.. _Tk-option-data-types:
+
 Tk option data types
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -769,12 +774,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.
@@ -1991,6 +2000,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()
 
@@ -2451,6 +2461,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
@@ -5658,6 +5670,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.