Deploy preview for PR 1231 🛫

Author: pydoc-zh-tw[bot]

pr-preview/pr-1231/_sources/faq/design.rst.txt

@@ -428,6 +428,8 @@ you can always change a list's elements.  Only immutable elements can be used as
 dictionary keys, and hence only tuples and not lists can be used as keys.
 
 
+.. _how-are-lists-implemented:
+
 How are lists implemented in CPython?
 -------------------------------------
 
@@ -443,6 +445,10 @@ cleverness is applied to improve the performance of appending items repeatedly;
 when the array must be grown, some extra space is allocated so the next few
 times don't require an actual resize.
 
+See :ref:`time-complexity` for the costs of the various list operations.
+
+
+.. _how-are-dictionaries-implemented:
 
 How are dictionaries implemented in CPython?
 --------------------------------------------
@@ -460,6 +466,8 @@ internal array where the value will be stored.  Assuming that you're storing
 keys that all have different hash values, this means that dictionaries take
 constant time -- *O*\ (1), in Big-O notation -- to retrieve a key.
 
+See :ref:`time-complexity` for the costs of the various dictionary operations.
+
 
 Why must dictionary keys be immutable?
 --------------------------------------

pr-preview/pr-1231/_sources/faq/programming.rst.txt

@@ -1136,7 +1136,7 @@ What is the most efficient way to concatenate many strings together?
 :class:`str` and :class:`bytes` objects are immutable, therefore concatenating
 many strings together is inefficient as each concatenation creates a new
 object.  In the general case, the total runtime cost is quadratic in the
-total string length.
+total string length.  See :ref:`time-complexity` for more information.
 
 To accumulate many :class:`str` objects, the recommended idiom is to place
 them into a list and call :meth:`str.join` at the end::

pr-preview/pr-1231/_sources/glossary.rst.txt

@@ -942,7 +942,7 @@ Glossary
    list
       A built-in Python :term:`sequence`.  Despite its name it is more akin
       to an array in other languages than to a linked list since access to
-      elements is *O*\ (1).
+      elements is *O*\ (1).  See :ref:`time-complexity`.
 
    list comprehension
       A compact way to process all or part of the elements in a sequence and

pr-preview/pr-1231/_sources/howto/curses.rst.txt

@@ -298,15 +298,18 @@ the next subsection.
 
 The :meth:`~curses.window.addstr` method takes a Python string or
 bytestring as the value to be displayed.  The contents of bytestrings
-are sent to the terminal as-is.  Strings are encoded to bytes using
-the value of the window's :attr:`~window.encoding` attribute; this defaults to
-the default system encoding as returned by :func:`locale.getencoding`.
+are sent to the terminal as-is.
+On a build without wide-character support strings are encoded
+using the value of the window's :attr:`~window.encoding` attribute;
+this defaults to the default system encoding
+as returned by :func:`locale.getencoding`.
 
 The :meth:`~curses.window.addch` methods take a character, which can be
 either a string of length 1, a bytestring of length 1, or an integer.
 
-Constants are provided for extension characters; these constants are
-integers greater than 255.  For example, :const:`ACS_PLMINUS` is a +/-
+Constants are provided for the characters of the terminal's alternate
+character set.
+For example, :const:`ACS_PLMINUS` is a +/-
 symbol, and :const:`ACS_ULCORNER` is the upper left corner of a box
 (handy for drawing borders).  You can also use the appropriate Unicode
 character.
@@ -320,11 +323,11 @@ won't be distracting; it can be confusing to have the cursor blinking at some
 apparently random location.
 
 If your application doesn't need a blinking cursor at all, you can
-call ``curs_set(False)`` to make it invisible.  For compatibility
-with older curses versions, there's a ``leaveok(bool)`` function
-that's a synonym for :func:`~curses.curs_set`.  When *bool* is true, the
-curses library will attempt to suppress the flashing cursor, and you
-won't need to worry about leaving it in odd locations.
+call ``curs_set(False)`` to make it invisible.
+The window method :meth:`~curses.window.leaveok` does something different:
+when its argument is true,
+curses leaves the cursor wherever the last update put it,
+instead of moving it back to the window's cursor position.
 
 
 Attributes and Color
@@ -430,40 +433,48 @@ The C curses library offers only very simple input mechanisms. Python's
 :mod:`curses` module adds a basic text-input widget.  (Other libraries
 such as :pypi:`Urwid` have more extensive collections of widgets.)
 
-There are two methods for getting input from a window:
+There are three methods for getting input from a window:
 
-* :meth:`~curses.window.getch` refreshes the screen and then waits for
+* :meth:`~curses.window.get_wch` refreshes the screen and then waits for
   the user to hit a key, displaying the key if :func:`~curses.echo` has been
   called earlier.  You can optionally specify a coordinate to which
   the cursor should be moved before pausing.
 
-* :meth:`~curses.window.getkey` does the same thing but converts the
-  integer to a string.  Individual characters are returned as
-  1-character strings, and special keys such as function keys return
-  longer strings containing a key name such as ``KEY_UP`` or ``^G``.
+* :meth:`~curses.window.getch` does the same thing but returns the code of
+  the key instead of a character.
+  With ncurses this is a single byte of the key's encoding in the current
+  locale, so a character encoded with several bytes takes several calls,
+  one byte per call.
+
+* :meth:`~curses.window.getkey` does the same as :meth:`!getch` but returns
+  a string:
+  an ordinary key as a 1-character string,
+  and a special key as its name, such as ``KEY_UP``.
 
 It's possible to not wait for the user using the
 :meth:`~curses.window.nodelay` window method. After ``nodelay(True)``,
-:meth:`!getch` and :meth:`!getkey` for the window become
-non-blocking. To signal that no input is ready, :meth:`!getch` returns
-``curses.ERR`` (a value of -1) and :meth:`!getkey` raises an exception.
+the reads for the window become non-blocking.
+To signal that no input is ready,
+:meth:`!get_wch` and :meth:`!getkey` raise an exception,
+and :meth:`!getch` returns ``-1``.
 There's also a :func:`~curses.halfdelay` function, which can be used to (in
-effect) set a timer on each :meth:`!getch`; if no input becomes
+effect) set a timer on each read; if no input becomes
 available within a specified delay (measured in tenths of a second),
-curses raises an exception.
+the read fails the same way.
 
-The :meth:`!getch` method returns an integer; if it's between 0 and 255, it
-represents the ASCII code of the key pressed.  Values greater than 255 are
-special keys such as Page Up, Home, or the cursor keys. You can compare the
-value returned to constants such as :const:`curses.KEY_PPAGE`,
+Special keys such as Page Up, Home, or the cursor keys are returned by all
+three as one of the :ref:`KEY_* constants <curses-key-constants>`,
+all larger than 255.
+You can compare the value returned to constants such as
+:const:`curses.KEY_PPAGE`,
 :const:`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`.  The main loop of
 your program may look something like this::
 
    while True:
-       c = stdscr.getch()
-       if c == ord('p'):
+       c = stdscr.get_wch()
+       if c == 'p':
            PrintDocument()
-       elif c == ord('q'):
+       elif c == 'q':
            break  # Exit the while loop
        elif c == curses.KEY_HOME:
            x = y = 0
@@ -475,15 +486,16 @@ conversion functions  that take either integer or 1-character-string arguments
 and return the same type.  For example, :func:`curses.ascii.ctrl` returns the
 control character corresponding to its argument.
 
-There's also a method to retrieve an entire string,
+There's also a method to retrieve an entire line,
 :meth:`~curses.window.getstr`.  It isn't used very often, because its
 functionality is quite limited; the only editing keys available are
-the backspace key and the Enter key, which terminates the string.  It
-can optionally be limited to a fixed number of characters. ::
+the erase and kill characters, and the Enter key, which terminates the line.
+It returns a bytes object,
+and can optionally be limited to a fixed number of bytes. ::
 
    curses.echo()            # Enable echoing of characters
 
-   # Get a 15-character string, with the cursor on the top line
+   # Get a line of at most 15 bytes, with the cursor on the top line
    s = stdscr.getstr(0,0, 15)
 
 The :mod:`curses.textpad` module supplies a text box that supports an

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

@@ -9,59 +9,69 @@
 
 --------------
 
-The :mod:`!atexit` module defines functions to register and unregister cleanup
-functions.  Functions thus registered are automatically executed upon normal
-interpreter termination.  :mod:`!atexit` runs these functions in the *reverse*
-order in which they were registered; if you register ``A``, ``B``, and ``C``,
-at interpreter termination time they will be run in the order ``C``, ``B``,
-``A``.
-
-**Note:** The functions registered via this module are not called when the
+The :mod:`!atexit` module defines functions to register and unregister
+:dfn:`exit handlers`: functions that are automatically executed
+"at exit", that is, upon normal program termination (for instance,
+if :func:`sys.exit` is called or the main module's execution completes)
+or, more generally, upon :term:`interpreter shutdown`.
+
+At exit, all registered exit handlers are called
+in the *reverse* order in which they were registered.
+If you register ``A``, ``B``, and ``C``, at interpreter shutdown time they
+will be run in the order ``C``, ``B``, ``A``.
+The assumption is that lower level modules will normally be imported before
+higher level modules and thus must be cleaned up later.
+
+If an exception is raised during execution of an exit handler, a traceback is
+printed (unless :exc:`SystemExit` is raised) and the exception information is
+saved.  After all exit handlers have had a chance to run, the last exception to
+be raised is re-raised.
+
+In programs that use multiple interpreters, each interpreter has its own stack
+of exit handlers, which are executed when the interpreter shuts down
+(for example, with :meth:`concurrent.interpreters.Interpreter.close` or the
+C API :c:func:`Py_EndInterpreter`).
+Registration functions in this module only affect the interpreter they are
+called from.
+
+**Note:** Exit handlers are not called when the
 program is killed by a signal not handled by Python, when a Python fatal
 internal error is detected, or when :func:`os._exit` is called.
 
 **Note:** The effect of registering or unregistering functions from within
 a cleanup function is undefined.
 
-.. versionchanged:: 3.7
-    When used with C-API subinterpreters, registered functions
-    are local to the interpreter they were registered in.
+.. warning::
+   When writing exit handlers, especially in C API extensions, keep in mind
+   that other exit handlers may still run arbitrary Python code after you
+   clean up.
+   Such code should succeed or fail with an exception, rather than crash.
 
-.. function:: register(func, *args, **kwargs)
+.. versionchanged:: 3.12
+   Attempts to start a new thread or :func:`os.fork` a new process
+   in an exit handler now leads to :exc:`RuntimeError`.
+   Previously, this could cause race conditions between the main Python
+   runtime thread freeing thread states while internal :mod:`threading`
+   routines or the new process try to use that state, which could lead to
+   crashes rather than clean shutdown.
 
-   Register *func* as a function to be executed at termination.  Any optional
-   arguments that are to be passed to *func* must be passed as arguments to
-   :func:`register`.  It is possible to register the same function and arguments
-   more than once.
+.. versionchanged:: 3.7
+   When used with subinterpreters, registered functions
+   are local to the interpreter they were registered in.
 
-   At normal program termination (for instance, if :func:`sys.exit` is called or
-   the main module's execution completes), all functions registered are called in
-   last in, first out order.  The assumption is that lower level modules will
-   normally be imported before higher level modules and thus must be cleaned up
-   later.
+.. function:: register(func, *args, **kwargs)
 
-   If an exception is raised during execution of the exit handlers, a traceback is
-   printed (unless :exc:`SystemExit` is raised) and the exception information is
-   saved.  After all exit handlers have had a chance to run, the last exception to
-   be raised is re-raised.
+   Register *func* as an exit handler.
+   Any optional arguments that are to be passed to *func* must be passed as
+   arguments to :func:`register`.
+   It is possible to register the same function and arguments more than once.
 
    This function returns *func*, which makes it possible to use it as a
    decorator.
 
-   .. warning::
-       Starting new threads or calling :func:`os.fork` from a registered
-       function can lead to race condition between the main Python
-       runtime thread freeing thread states while internal :mod:`threading`
-       routines or the new process try to use that state. This can lead to
-       crashes rather than clean shutdown.
-
-   .. versionchanged:: 3.12
-       Attempts to start a new thread or :func:`os.fork` a new process
-       in a registered function now leads to :exc:`RuntimeError`.
-
 .. function:: unregister(func)
 
-   Remove *func* from the list of functions to be run at interpreter shutdown.
+   Remove *func* from the list of exit handlers.
    :func:`unregister` silently does nothing if *func* was not previously
    registered.  If *func* has been registered more than once, every occurrence
    of that function in the :mod:`!atexit` call stack will be removed.  Equality

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

@@ -987,7 +987,8 @@ Window objects
 
 .. attribute:: window.encoding
 
-   Encoding used to encode method arguments (Unicode strings and characters).
+   Encoding used to encode the string arguments of the methods and to decode
+   their results on a build without wide-character support.
    The encoding attribute is inherited from the parent window when a subwindow
    is created, for example with :meth:`window.subwin`.
    By default, current locale encoding is used (see :func:`locale.getencoding`).

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

@@ -44,6 +44,7 @@ the `Python Package Index <https://pypi.org>`_.
    stdtypes.rst
    exceptions.rst
    threadsafety.rst
+   time-complexity.rst
 
    text.rst
    binary.rst

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

@@ -468,6 +468,10 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
       Functions wrapped in :func:`functools.partial` now return ``True`` if the
       wrapped function is a Python generator function.
 
+   .. versionchanged:: 3.10.6
+      :term:`Duck-typed <duck-typing>` function-like objects now return
+      ``True`` if their code object has the :data:`CO_GENERATOR` flag.
+
    .. versionchanged:: 3.13
       Functions wrapped in :func:`functools.partialmethod` now return ``True``
       if the wrapped function is a Python generator function.
@@ -490,6 +494,10 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
       Functions wrapped in :func:`functools.partial` now return ``True`` if the
       wrapped function is a :term:`coroutine function`.
 
+   .. versionchanged:: 3.10.6
+      :term:`Duck-typed <duck-typing>` function-like objects now return
+      ``True`` if their code object has the :data:`CO_COROUTINE` flag.
+
    .. versionchanged:: 3.12
       Sync functions marked with :func:`markcoroutinefunction` now return
       ``True``.
@@ -564,6 +572,10 @@ attributes (see :ref:`import-mod-attrs` for module attributes):
       Functions wrapped in :func:`functools.partial` now return ``True`` if the
       wrapped function is an :term:`asynchronous generator` function.
 
+   .. versionchanged:: 3.10.6
+      :term:`Duck-typed <duck-typing>` function-like objects now return
+      ``True`` if their code object has the :data:`CO_ASYNC_GENERATOR` flag.
+
    .. versionchanged:: 3.13
       Functions wrapped in :func:`functools.partialmethod` now return ``True``
       if the wrapped function is a :term:`asynchronous generator` function.

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

@@ -999,6 +999,9 @@ The ``in`` and ``not in`` operations have the same priorities as the
 comparison operations. The ``+`` (concatenation) and ``*`` (repetition)
 operations have the same priority as the corresponding numeric operations. [3]_
 
+See :ref:`time-complexity` for the costs of the various sequence
+operations.
+
 .. index::
    triple: operations on; sequence; types
    pair: built-in function; len
@@ -1121,6 +1124,8 @@ Notes:
    "end" values (which end depends on the sign of *k*).  Note, *k* cannot be zero.
    If *k* is ``None``, it is treated like ``1``.
 
+.. _typesseq-repeated-concatenation:
+
 (6)
    Concatenating immutable sequences always results in a new object.  This
    means that building up a sequence by repeated concatenation will have a
@@ -5083,6 +5088,7 @@ computing mathematical operations such as intersection, union, difference, and
 symmetric difference.
 (For other containers see the built-in :class:`dict`, :class:`list`,
 and :class:`tuple` classes, and the :mod:`collections` module.)
+See :ref:`time-complexity` for the costs of the various set operations.
 
 Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
 set``.  Being an unordered collection, sets do not record element position or
@@ -5306,6 +5312,8 @@ Mappings are mutable objects.  There is currently only one standard mapping
 type, the :dfn:`dictionary`.  (For other containers see the built-in
 :class:`list`, :class:`set`, and :class:`tuple` classes, and the
 :mod:`collections` module.)
+See :ref:`time-complexity` for the costs of the various dictionary
+operations.
 
 A dictionary's keys are *almost* arbitrary values.  Values that are not
 :term:`hashable`, that is, values containing lists, dictionaries or other