diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/init_config.rst | 12 | ||||
| -rw-r--r-- | Doc/c-api/object.rst | 18 | ||||
| -rw-r--r-- | Doc/c-api/refcounting.rst | 9 | ||||
| -rw-r--r-- | Doc/deprecations/index.rst | 2 | ||||
| -rw-r--r-- | Doc/deprecations/pending-removal-in-3.19.rst | 8 | ||||
| -rw-r--r-- | Doc/library/ast.rst | 34 | ||||
| -rw-r--r-- | Doc/library/asyncio-eventloop.rst | 10 | ||||
| -rw-r--r-- | Doc/library/cmdline.rst | 2 | ||||
| -rw-r--r-- | Doc/library/ctypes.rst | 15 | ||||
| -rw-r--r-- | Doc/library/gc.rst | 5 | ||||
| -rw-r--r-- | Doc/library/getpass.rst | 11 | ||||
| -rw-r--r-- | Doc/library/heapq.rst | 110 | ||||
| -rw-r--r-- | Doc/library/pathlib.rst | 8 | ||||
| -rw-r--r-- | Doc/library/pdb.rst | 8 | ||||
| -rw-r--r-- | Doc/library/subprocess.rst | 18 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 58 | ||||
| -rw-r--r-- | Doc/library/threading.rst | 127 | ||||
| -rw-r--r-- | Doc/library/typing.rst | 40 | ||||
| -rw-r--r-- | Doc/library/urllib.request.rst | 18 | ||||
| -rw-r--r-- | Doc/using/cmdline.rst | 47 | ||||
| -rw-r--r-- | Doc/using/configure.rst | 23 | ||||
| -rw-r--r-- | Doc/using/windows.rst | 19 | ||||
| -rw-r--r-- | Doc/whatsnew/2.6.rst | 2 | ||||
| -rw-r--r-- | Doc/whatsnew/3.14.rst | 347 |
24 files changed, 783 insertions, 168 deletions
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index bc5b236393b..1f413a802c3 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -363,7 +363,7 @@ Configuration Options - Read-only * - ``"import_time"`` - :c:member:`import_time <PyConfig.import_time>` - - ``bool`` + - ``int`` - Read-only * - ``"inspect"`` - :c:member:`inspect <PyConfig.inspect>` @@ -1477,13 +1477,19 @@ PyConfig .. c:member:: int import_time - If non-zero, profile import time. + If ``1``, profile import time. + If ``2``, include additional output that indicates + when an imported module has already been loaded. - Set the ``1`` by the :option:`-X importtime <-X>` option and the + Set by the :option:`-X importtime <-X>` option and the :envvar:`PYTHONPROFILEIMPORTTIME` environment variable. Default: ``0``. + .. versionchanged:: next + + Added support for ``import_time = 2`` + .. c:member:: int inspect Enter interactive mode after executing a script or a command. diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index efad4d215b1..0fd159f1eb8 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -737,3 +737,21 @@ Object Protocol caller must hold a :term:`strong reference` to *obj* when calling this. .. versionadded:: 3.14 + +.. c:function:: int PyUnstable_Object_IsUniquelyReferenced(PyObject *op) + + Determine if *op* only has one reference. + + On GIL-enabled builds, this function is equivalent to + :c:expr:`Py_REFCNT(op) == 1`. + + On a :term:`free threaded <free threading>` build, this checks if *op*'s + :term:`reference count` is equal to one and additionally checks if *op* + is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not** + thread-safe on free threaded builds; prefer this function. + + The caller must hold an :term:`attached thread state`, despite the fact + that this function doesn't call into the Python interpreter. This function + cannot fail. + + .. versionadded:: 3.14 diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst index 83febcf70a5..b23f016f9b0 100644 --- a/Doc/c-api/refcounting.rst +++ b/Doc/c-api/refcounting.rst @@ -23,7 +23,14 @@ of Python objects. Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count. - See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`. + .. note:: + + On :term:`free threaded <free threading>` builds of Python, returning 1 + isn't sufficient to determine if it's safe to treat *o* as having no + access by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced` + for that instead. + + See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`. .. versionchanged:: 3.10 :c:func:`Py_REFCNT()` is changed to the inline static function. diff --git a/Doc/deprecations/index.rst b/Doc/deprecations/index.rst index bb78f7b3607..d064f2bec42 100644 --- a/Doc/deprecations/index.rst +++ b/Doc/deprecations/index.rst @@ -7,6 +7,8 @@ Deprecations .. include:: pending-removal-in-3.17.rst +.. include:: pending-removal-in-3.19.rst + .. include:: pending-removal-in-future.rst C API deprecations diff --git a/Doc/deprecations/pending-removal-in-3.19.rst b/Doc/deprecations/pending-removal-in-3.19.rst new file mode 100644 index 00000000000..3936f63ca5b --- /dev/null +++ b/Doc/deprecations/pending-removal-in-3.19.rst @@ -0,0 +1,8 @@ +Pending removal in Python 3.19 +------------------------------ + +* :mod:`ctypes`: + + * Implicitly switching to the MSVC-compatible struct layout by setting + :attr:`~ctypes.Structure._pack_` but not :attr:`~ctypes.Structure._layout_` + on non-Windows platforms. diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 776c63d1f0f..c9ae0abdd66 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -1,4 +1,4 @@ -:mod:`!ast` --- Abstract Syntax Trees +:mod:`!ast` --- Abstract syntax trees ===================================== .. module:: ast @@ -29,7 +29,7 @@ compiled into a Python code object using the built-in :func:`compile` function. .. _abstract-grammar: -Abstract Grammar +Abstract grammar ---------------- The abstract grammar is currently defined as follows: @@ -2156,10 +2156,10 @@ Async and await of :class:`ast.operator`, :class:`ast.unaryop`, :class:`ast.cmpop`, :class:`ast.boolop` and :class:`ast.expr_context`) on the returned tree will be singletons. Changes to one will be reflected in all other - occurrences of the same value (e.g. :class:`ast.Add`). + occurrences of the same value (for example, :class:`ast.Add`). -:mod:`ast` Helpers +:mod:`ast` helpers ------------------ Apart from the node classes, the :mod:`ast` module defines these utility functions @@ -2484,7 +2484,7 @@ and classes for traversing abstract syntax trees: .. _ast-compiler-flags: -Compiler Flags +Compiler flags -------------- The following flags may be passed to :func:`compile` in order to change @@ -2533,7 +2533,7 @@ effects on the compilation of a program: .. _ast-cli: -Command-Line Usage +Command-line usage ------------------ .. versionadded:: 3.9 @@ -2572,6 +2572,28 @@ The following options are accepted: Indentation of nodes in AST (number of spaces). +.. option:: --feature-version <version> + + Python version in the format 3.x (for example, 3.10). Defaults to the + current version of the interpreter. + + .. versionadded:: next + +.. option:: -O <level> + --optimize <level> + + Optimization level for parser. Defaults to no optimization. + + .. versionadded:: next + +.. option:: --show-empty + + Show empty lists and fields that are ``None``. Defaults to not showing empty + objects. + + .. versionadded:: next + + If :file:`infile` is specified its contents are parsed to AST and dumped to stdout. Otherwise, the content is read from stdin. diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 8f561744fe4..e25f6e52efc 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -361,7 +361,7 @@ Creating Futures and Tasks .. versionadded:: 3.5.2 -.. method:: loop.create_task(coro, *, name=None, context=None) +.. method:: loop.create_task(coro, *, name=None, context=None, eager_start=None) Schedule the execution of :ref:`coroutine <coroutine>` *coro*. Return a :class:`Task` object. @@ -377,12 +377,20 @@ Creating Futures and Tasks custom :class:`contextvars.Context` for the *coro* to run in. The current context copy is created when no *context* is provided. + An optional keyword-only *eager_start* argument allows specifying + if the task should execute eagerly during the call to create_task, + or be scheduled later. If *eager_start* is not passed the mode set + by :meth:`loop.set_task_factory` will be used. + .. versionchanged:: 3.8 Added the *name* parameter. .. versionchanged:: 3.11 Added the *context* parameter. + .. versionchanged:: next + Added the *eager_start* parameter. + .. method:: loop.set_task_factory(factory) Set a task factory that will be used by diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst index f7ae2133a70..16c67ddbf7c 100644 --- a/Doc/library/cmdline.rst +++ b/Doc/library/cmdline.rst @@ -1,3 +1,5 @@ +.. _library-cmdline: + ++++++++++++++++++++++++++++++++++++ Modules command-line interface (CLI) ++++++++++++++++++++++++++++++++++++ diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 2825590400c..1b78b33b69f 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2754,6 +2754,16 @@ fields, or any other data types containing pointer type fields. when :attr:`_fields_` is assigned, otherwise it will have no effect. Setting this attribute to 0 is the same as not setting it at all. + This is only implemented for the MSVC-compatible memory layout. + + .. deprecated-removed:: next 3.19 + + For historical reasons, if :attr:`!_pack_` is non-zero, + the MSVC-compatible layout will be used by default. + On non-Windows platforms, this default is deprecated and is slated to + become an error in Python 3.19. + If it is intended, set :attr:`~Structure._layout_` to ``'ms'`` + explicitly. .. attribute:: _align_ @@ -2782,12 +2792,15 @@ fields, or any other data types containing pointer type fields. Currently the default will be: - On Windows: ``"ms"`` - - When :attr:`~Structure._pack_` is specified: ``"ms"`` + - When :attr:`~Structure._pack_` is specified: ``"ms"``. + (This is deprecated; see :attr:`~Structure._pack_` documentation.) - Otherwise: ``"gcc-sysv"`` :attr:`!_layout_` must already be defined when :attr:`~Structure._fields_` is assigned, otherwise it will have no effect. + .. versionadded:: next + .. attribute:: _anonymous_ An optional sequence that lists the names of unnamed (anonymous) fields. diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst index 480a9dec7f1..7ccb0e6bdf9 100644 --- a/Doc/library/gc.rst +++ b/Doc/library/gc.rst @@ -128,6 +128,11 @@ The :mod:`gc` module provides the following functions: starts. For each collection, all the objects in the young generation and some fraction of the old generation is collected. + In the free-threaded build, the increase in process memory usage is also + checked before running the collector. If the memory usage has not increased + by 10% since the last collection and the net number of object allocations + has not exceeded 40 times *threshold0*, the collection is not run. + The fraction of the old generation that is collected is **inversely** proportional to *threshold1*. The larger *threshold1* is, the slower objects in the old generation are collected. diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst index 3b5296f9ec6..38b78dc3299 100644 --- a/Doc/library/getpass.rst +++ b/Doc/library/getpass.rst @@ -16,7 +16,7 @@ The :mod:`getpass` module provides two functions: -.. function:: getpass(prompt='Password: ', stream=None) +.. function:: getpass(prompt='Password: ', stream=None, *, echo_char=None) Prompt the user for a password without echoing. The user is prompted using the string *prompt*, which defaults to ``'Password: '``. On Unix, the @@ -25,6 +25,12 @@ The :mod:`getpass` module provides two functions: (:file:`/dev/tty`) or if that is unavailable to ``sys.stderr`` (this argument is ignored on Windows). + The *echo_char* argument controls how user input is displayed while typing. + If *echo_char* is ``None`` (default), input remains hidden. Otherwise, + *echo_char* must be a printable ASCII string and each 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 issuing a :exc:`GetPassWarning`. @@ -33,6 +39,9 @@ The :mod:`getpass` module provides two functions: If you call getpass from within IDLE, the input may be done in the terminal you launched IDLE from rather than the idle window itself. + .. versionchanged:: next + Added the *echo_char* parameter for keyboard feedback. + .. exception:: GetPassWarning A :exc:`UserWarning` subclass issued when password input may be echoed. diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index d3c4b920ba5..2bd0162a982 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -16,40 +16,56 @@ This module provides an implementation of the heap queue algorithm, also known as the priority queue algorithm. -Heaps are binary trees for which every parent node has a value less than or -equal to any of its children. We refer to this condition as the heap invariant. +Min-heaps are binary trees for which every parent node has a value less than +or equal to any of its children. +We refer to this condition as the heap invariant. -This implementation uses arrays for which -``heap[k] <= heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k*, counting -elements from zero. For the sake of comparison, non-existing elements are -considered to be infinite. The interesting property of a heap is that its -smallest element is always the root, ``heap[0]``. +For min-heaps, this implementation uses lists for which +``heap[k] <= heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k* for which +the compared elements exist. Elements are counted from zero. The interesting +property of a min-heap is that its smallest element is always the root, +``heap[0]``. -The API below differs from textbook heap algorithms in two aspects: (a) We use -zero-based indexing. This makes the relationship between the index for a node -and the indexes for its children slightly less obvious, but is more suitable -since Python uses zero-based indexing. (b) Our pop method returns the smallest -item, not the largest (called a "min heap" in textbooks; a "max heap" is more -common in texts because of its suitability for in-place sorting). +Max-heaps satisfy the reverse invariant: every parent node has a value +*greater* than any of its children. These are implemented as lists for which +``maxheap[2*k+1] <= maxheap[k]`` and ``maxheap[2*k+2] <= maxheap[k]`` for all +*k* for which the compared elements exist. +The root, ``maxheap[0]``, contains the *largest* element; +``heap.sort(reverse=True)`` maintains the max-heap invariant. -These two make it possible to view the heap as a regular Python list without -surprises: ``heap[0]`` is the smallest item, and ``heap.sort()`` maintains the -heap invariant! +The :mod:`!heapq` API differs from textbook heap algorithms in two aspects: (a) +We use zero-based indexing. This makes the relationship between the index for +a node and the indexes for its children slightly less obvious, but is more +suitable since Python uses zero-based indexing. (b) Textbooks often focus on +max-heaps, due to their suitability for in-place sorting. Our implementation +favors min-heaps as they better correspond to Python :class:`lists <list>`. -To create a heap, use a list initialized to ``[]``, or you can transform a -populated list into a heap via function :func:`heapify`. +These two aspects make it possible to view the heap as a regular Python list +without surprises: ``heap[0]`` is the smallest item, and ``heap.sort()`` +maintains the heap invariant! -The following functions are provided: +Like :meth:`list.sort`, this implementation uses only the ``<`` operator +for comparisons, for both min-heaps and max-heaps. + +In the API below, and in this documentation, the unqualified term *heap* +generally refers to a min-heap. +The API for max-heaps is named using a ``_max`` suffix. + +To create a heap, use a list initialized as ``[]``, or transform an existing list +into a min-heap or max-heap using the :func:`heapify` or :func:`heapify_max` +functions, respectively. + +The following functions are provided for min-heaps: .. function:: heappush(heap, item) - Push the value *item* onto the *heap*, maintaining the heap invariant. + Push the value *item* onto the *heap*, maintaining the min-heap invariant. .. function:: heappop(heap) - Pop and return the smallest item from the *heap*, maintaining the heap + Pop and return the smallest item from the *heap*, maintaining the min-heap invariant. If the heap is empty, :exc:`IndexError` is raised. To access the smallest item without popping it, use ``heap[0]``. @@ -63,7 +79,7 @@ The following functions are provided: .. function:: heapify(x) - Transform list *x* into a heap, in-place, in linear time. + Transform list *x* into a min-heap, in-place, in linear time. .. function:: heapreplace(heap, item) @@ -82,6 +98,56 @@ The following functions are provided: on the heap. +For max-heaps, the following functions are provided: + + +.. function:: heapify_max(x) + + Transform list *x* into a max-heap, in-place, in linear time. + + .. versionadded:: next + + +.. function:: heappush_max(heap, item) + + Push the value *item* onto the max-heap *heap*, maintaining the max-heap + invariant. + + .. versionadded:: next + + +.. function:: heappop_max(heap) + + Pop and return the largest item from the max-heap *heap*, maintaining the + max-heap invariant. If the max-heap is empty, :exc:`IndexError` is raised. + To access the largest item without popping it, use ``maxheap[0]``. + + .. versionadded:: next + + +.. function:: heappushpop_max(heap, item) + + Push *item* on the max-heap *heap*, then pop and return the largest item + from *heap*. + The combined action runs more efficiently than :func:`heappush_max` + followed by a separate call to :func:`heappop_max`. + + .. versionadded:: next + + +.. function:: heapreplace_max(heap, item) + + Pop and return the largest item from the max-heap *heap* and also push the + new *item*. + The max-heap size doesn't change. If the max-heap is empty, + :exc:`IndexError` is raised. + + The value returned may be smaller than the *item* added. Refer to the + analogous function :func:`heapreplace` for detailed usage notes. + + .. versionadded:: next + + The module also offers three general purpose functions based on heaps. diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index b8298690286..acb91812818 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -872,10 +872,10 @@ conforming to :rfc:`8089`. .. versionadded:: 3.13 .. versionchanged:: next - If a URL authority (e.g. a hostname) is present and resolves to a local - address, it is discarded. If an authority is present and *doesn't* - resolve to a local address, then on Windows a UNC path is returned (as - before), and on other platforms a :exc:`ValueError` is raised. + The URL authority is discarded if it matches the local hostname. + Otherwise, if the authority isn't empty or ``localhost``, then on + Windows a UNC path is returned (as before), and on other platforms a + :exc:`ValueError` is raised. .. method:: Path.as_uri() diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index 3c8c0707499..a0304edddf6 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -243,7 +243,7 @@ The ``run*`` functions and :func:`set_trace` are aliases for instantiating the access further features, you have to do this yourself: .. class:: Pdb(completekey='tab', stdin=None, stdout=None, skip=None, \ - nosigint=False, readrc=True, mode=None, backend=None) + nosigint=False, readrc=True, mode=None, backend=None, colorize=False) :class:`Pdb` is the debugger class. @@ -273,6 +273,9 @@ access further features, you have to do this yourself: is passed, the default backend will be used. See :func:`set_default_backend`. Otherwise the supported backends are ``'settrace'`` and ``'monitoring'``. + The *colorize* argument, if set to ``True``, will enable colorized output in the + debugger, if color is supported. This will highlight source code displayed in pdb. + Example call to enable tracing with *skip*:: import pdb; pdb.Pdb(skip=['django.*']).set_trace() @@ -295,6 +298,9 @@ access further features, you have to do this yourself: .. versionadded:: 3.14 Added the *backend* argument. + .. versionadded:: 3.14 + Added the *colorize* argument. + .. versionchanged:: 3.14 Inline breakpoints like :func:`breakpoint` or :func:`pdb.set_trace` will always stop the program at calling frame, ignoring the *skip* pattern (if any). diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 05d09e304b3..028a7861f36 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -1525,6 +1525,24 @@ handling consistency are valid for these functions. Notes ----- +.. _subprocess-timeout-behavior: + +Timeout Behavior +^^^^^^^^^^^^^^^^ + +When using the ``timeout`` parameter in functions like :func:`run`, +:meth:`Popen.wait`, or :meth:`Popen.communicate`, +users should be aware of the following behaviors: + +1. **Process Creation Delay**: The initial process creation itself cannot be interrupted + on many platform APIs. This means that even when specifying a timeout, you are not + guaranteed to see a timeout exception until at least after however long process + creation takes. + +2. **Extremely Small Timeout Values**: Setting very small timeout values (such as a few + milliseconds) may result in almost immediate :exc:`TimeoutExpired` exceptions because + process creation and system scheduling inherently require time. + .. _converting-argument-sequence: Converting an argument sequence to a string on Windows diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index fbfd5e1e75b..a5c4ffa38fe 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1282,6 +1282,64 @@ always available. Unless explicitly noted otherwise, all variables are read-only .. versionadded:: 3.5 +.. data:: _jit + + Utilities for observing just-in-time compilation. + + .. impl-detail:: + + JIT compilation is an *experimental implementation detail* of CPython. + ``sys._jit`` is not guaranteed to exist or behave the same way in all + Python implementations, versions, or build configurations. + + .. versionadded:: next + + .. function:: _jit.is_available() + + Return ``True`` if the current Python executable supports JIT compilation, + and ``False`` otherwise. This can be controlled by building CPython with + the ``--experimental-jit`` option on Windows, and the + :option:`--enable-experimental-jit` option on all other platforms. + + .. function:: _jit.is_enabled() + + Return ``True`` if JIT compilation is enabled for the current Python + process (implies :func:`sys._jit.is_available`), and ``False`` otherwise. + If JIT compilation is available, this can be controlled by setting the + :envvar:`PYTHON_JIT` environment variable to ``0`` (disabled) or ``1`` + (enabled) at interpreter startup. + + .. function:: _jit.is_active() + + Return ``True`` if the topmost Python frame is currently executing JIT + code (implies :func:`sys._jit.is_enabled`), and ``False`` otherwise. + + .. note:: + + This function is intended for testing and debugging the JIT itself. + It should be avoided for any other purpose. + + .. note:: + + Due to the nature of tracing JIT compilers, repeated calls to this + function may give surprising results. For example, branching on its + return value will likely lead to unexpected behavior (if doing so + causes JIT code to be entered or exited): + + .. code-block:: pycon + + >>> for warmup in range(BIG_NUMBER): + ... # This line is "hot", and is eventually JIT-compiled: + ... if sys._jit.is_active(): + ... # This line is "cold", and is run in the interpreter: + ... assert sys._jit.is_active() + ... + Traceback (most recent call last): + File "<stdin>", line 5, in <module> + assert sys._jit.is_active() + ~~~~~~~~~~~~~~~~~~^^ + AssertionError + .. data:: last_exc This variable is not always defined; it is set to the exception instance diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index d948493c210..de9ee427bd7 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -260,23 +260,132 @@ All of the methods described below are executed atomically. Thread-Local Data ----------------- -Thread-local data is data whose values are thread specific. To manage -thread-local data, just create an instance of :class:`local` (or a -subclass) and store attributes on it:: +Thread-local data is data whose values are thread specific. If you +have data that you want to be local to a thread, create a +:class:`local` object and use its attributes:: - mydata = threading.local() - mydata.x = 1 + >>> mydata = local() + >>> mydata.number = 42 + >>> mydata.number + 42 -The instance's values will be different for separate threads. +You can also access the :class:`local`-object's dictionary:: + + >>> mydata.__dict__ + {'number': 42} + >>> mydata.__dict__.setdefault('widgets', []) + [] + >>> mydata.widgets + [] + +If we access the data in a different thread:: + + >>> log = [] + >>> def f(): + ... items = sorted(mydata.__dict__.items()) + ... log.append(items) + ... mydata.number = 11 + ... log.append(mydata.number) + + >>> import threading + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + >>> log + [[], 11] + +we get different data. Furthermore, changes made in the other thread +don't affect data seen in this thread:: + + >>> mydata.number + 42 + +Of course, values you get from a :class:`local` object, including their +:attr:`~object.__dict__` attribute, are for whatever thread was current +at the time the attribute was read. For that reason, you generally +don't want to save these values across threads, as they apply only to +the thread they came from. + +You can create custom :class:`local` objects by subclassing the +:class:`local` class:: + + >>> class MyLocal(local): + ... number = 2 + ... def __init__(self, /, **kw): + ... self.__dict__.update(kw) + ... def squared(self): + ... return self.number ** 2 + +This can be useful to support default values, methods and +initialization. Note that if you define an :py:meth:`~object.__init__` +method, it will be called each time the :class:`local` object is used +in a separate thread. This is necessary to initialize each thread's +dictionary. + +Now if we create a :class:`local` object:: + + >>> mydata = MyLocal(color='red') + +we have a default number:: + + >>> mydata.number + 2 + +an initial color:: + + >>> mydata.color + 'red' + >>> del mydata.color + +And a method that operates on the data:: + + >>> mydata.squared() + 4 + +As before, we can access the data in a separate thread:: + + >>> log = [] + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + >>> log + [[('color', 'red')], 11] + +without affecting this thread's data:: + + >>> mydata.number + 2 + >>> mydata.color + Traceback (most recent call last): + ... + AttributeError: 'MyLocal' object has no attribute 'color' + +Note that subclasses can define :term:`__slots__`, but they are not +thread local. They are shared across threads:: + + >>> class MyLocal(local): + ... __slots__ = 'number' + + >>> mydata = MyLocal() + >>> mydata.number = 42 + >>> mydata.color = 'red' + +So, the separate thread:: + + >>> thread = threading.Thread(target=f) + >>> thread.start() + >>> thread.join() + +affects what we see:: + + >>> mydata.number + 11 .. class:: local() A class that represents thread-local data. - For more details and extensive examples, see the documentation string of the - :mod:`!_threading_local` module: :source:`Lib/_threading_local.py`. - .. _thread-objects: diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 3afcba6e898..54cc3ea3311 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -1098,6 +1098,12 @@ These can be used as types in annotations. They all support subscription using Union[Union[int, str], float] == Union[int, str, float] + However, this does not apply to unions referenced through a type + alias, to avoid forcing evaluation of the underlying :class:`TypeAliasType`:: + + type A = Union[int, str] + Union[A, float] != Union[int, str, float] + * Unions of a single argument vanish, e.g.:: Union[int] == int # The constructor actually returns int @@ -1230,6 +1236,32 @@ These can be used as types in annotations. They all support subscription using is allowed as type argument to ``Literal[...]``, but type checkers may impose restrictions. See :pep:`586` for more details about literal types. + Additional details: + + * The arguments must be literal values and there must be at least one. + + * Nested ``Literal`` types are flattened, e.g.:: + + assert Literal[Literal[1, 2], 3] == Literal[1, 2, 3] + + However, this does not apply to ``Literal`` types referenced through a type + alias, to avoid forcing evaluation of the underlying :class:`TypeAliasType`:: + + type A = Literal[1, 2] + assert Literal[A, 3] != Literal[1, 2, 3] + + * Redundant arguments are skipped, e.g.:: + + assert Literal[1, 2, 1] == Literal[1, 2] + + * When comparing literals, the argument order is ignored, e.g.:: + + assert Literal[1, 2] == Literal[2, 1] + + * You cannot subclass or instantiate a ``Literal``. + + * You cannot write ``Literal[X][Y]``. + .. versionadded:: 3.8 .. versionchanged:: 3.9.1 @@ -1400,6 +1432,14 @@ These can be used as types in annotations. They all support subscription using int, ValueRange(3, 10), ctype("char") ] + However, this does not apply to ``Annotated`` types referenced through a type + alias, to avoid forcing evaluation of the underlying :class:`TypeAliasType`:: + + type From3To10[T] = Annotated[T, ValueRange(3, 10)] + assert Annotated[From3To10[int], ctype("char")] != Annotated[ + int, ValueRange(3, 10), ctype("char") + ] + Duplicated metadata elements are not removed:: assert Annotated[int, ValueRange(3, 10)] != Annotated[ diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index b7c0c7d5099..234827132bf 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -172,10 +172,10 @@ The :mod:`urllib.request` module defines the following functions: the URL ``///etc/hosts``. .. versionchanged:: next - The *add_scheme* argument was added. + The *add_scheme* parameter was added. -.. function:: url2pathname(url, *, require_scheme=False) +.. function:: url2pathname(url, *, require_scheme=False, resolve_host=False) Convert the given ``file:`` URL to a local path. This function uses :func:`~urllib.parse.unquote` to decode the URL. @@ -185,6 +185,13 @@ The :mod:`urllib.request` module defines the following functions: value should include the prefix; a :exc:`~urllib.error.URLError` is raised if it doesn't. + The URL authority is discarded if it is empty, ``localhost``, or the local + hostname. Otherwise, if *resolve_host* is set to true, the authority is + resolved using :func:`socket.gethostbyname` and discarded if it matches a + local IP address (as per :rfc:`RFC 8089 §3 <8089#section-3>`). If the + authority is still unhandled, then on Windows a UNC path is returned, and + on other platforms a :exc:`~urllib.error.URLError` is raised. + This example shows the function being used on Windows:: >>> from urllib.request import url2pathname @@ -198,14 +205,13 @@ The :mod:`urllib.request` module defines the following functions: :exc:`OSError` exception to be raised on Windows. .. versionchanged:: next - This function calls :func:`socket.gethostbyname` if the URL authority - isn't empty, ``localhost``, or the machine hostname. If the authority - resolves to a local IP address then it is discarded; otherwise, on + The URL authority is discarded if it matches the local hostname. + Otherwise, if the authority isn't empty or ``localhost``, then on Windows a UNC path is returned (as before), and on other platforms a :exc:`~urllib.error.URLError` is raised. .. versionchanged:: next - The *require_scheme* argument was added. + The *require_scheme* and *resolve_host* parameters were added. .. function:: getproxies() diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index fa7c9cddf9c..0095046fe1f 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -539,11 +539,21 @@ Miscellaneous options * ``-X importtime`` to show how long each import takes. It shows module name, cumulative time (including nested imports) and self time (excluding nested imports). Note that its output may be broken in multi-threaded - application. Typical usage is ``python3 -X importtime -c 'import - asyncio'``. See also :envvar:`PYTHONPROFILEIMPORTTIME`. + application. Typical usage is ``python -X importtime -c 'import asyncio'``. + + ``-X importtime=2`` enables additional output that indicates when an + imported module has already been loaded. In such cases, the string + ``cached`` will be printed in both time columns. + + See also :envvar:`PYTHONPROFILEIMPORTTIME`. .. versionadded:: 3.7 + .. versionchanged:: next + + Added ``-X importtime=2`` to also trace imports of loaded modules, + and reserved values other than ``1`` and ``2`` for future use. + * ``-X dev``: enable :ref:`Python Development Mode <devmode>`, introducing additional runtime checks that are too expensive to be enabled by default. See also :envvar:`PYTHONDEVMODE`. @@ -670,6 +680,13 @@ Miscellaneous options .. versionchanged:: 3.10 Removed the ``-X oldparser`` option. +.. versionremoved:: next + + :option:`!-J` is no longer reserved for use by Jython_, + and now has no special meaning. + + .. _Jython: https://www.jython.org/ + .. _using-on-controlling-color: Controlling color @@ -694,15 +711,6 @@ output. To control the color output only in the Python interpreter, the precedence over ``NO_COLOR``, which in turn takes precedence over ``FORCE_COLOR``. -Options you shouldn't use -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. option:: -J - - Reserved for use by Jython_. - -.. _Jython: https://www.jython.org/ - .. _using-on-envvars: @@ -984,12 +992,17 @@ conflict. .. envvar:: PYTHONPROFILEIMPORTTIME - If this environment variable is set to a non-empty string, Python will - show how long each import takes. + If this environment variable is set to ``1``, Python will show + how long each import takes. If set to ``2``, Python will include output for + imported modules that have already been loaded. This is equivalent to setting the :option:`-X` ``importtime`` option. .. versionadded:: 3.7 + .. versionchanged:: next + + Added ``PYTHONPROFILEIMPORTTIME=2`` to also trace imports of loaded modules. + .. envvar:: PYTHONASYNCIODEBUG @@ -1281,6 +1294,14 @@ conflict. .. versionadded:: 3.14 +.. envvar:: PYTHON_JIT + + On builds where experimental just-in-time compilation is available, this + variable can force the JIT to be disabled (``0``) or enabled (``1``) at + interpreter startup. + + .. versionadded:: 3.13 + Debug-mode variables ~~~~~~~~~~~~~~~~~~~~ diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index 3d3776acbc7..b914d3397b6 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -302,14 +302,21 @@ General Options .. option:: --enable-experimental-jit=[no|yes|yes-off|interpreter] - Indicate how to integrate the :ref:`JIT compiler <whatsnew313-jit-compiler>`. - - * ``no`` - build the interpreter without the JIT. - * ``yes`` - build the interpreter with the JIT. - * ``yes-off`` - build the interpreter with the JIT but disable it by default. - * ``interpreter`` - build the interpreter without the JIT, but with the tier 2 enabled interpreter. - - By convention, ``--enable-experimental-jit`` is a shorthand for ``--enable-experimental-jit=yes``. + Indicate how to integrate the :ref:`experimental just-in-time compiler <whatsnew314-jit-compiler>`. + + * ``no``: Don't build the JIT. + * ``yes``: Enable the JIT. To disable it at runtime, set the environment + variable :envvar:`PYTHON_JIT=0 <PYTHON_JIT>`. + * ``yes-off``: Build the JIT, but disable it by default. To enable it at + runtime, set the environment variable :envvar:`PYTHON_JIT=1 <PYTHON_JIT>`. + * ``interpreter``: Enable the "JIT interpreter" (only useful for those + debugging the JIT itself). To disable it at runtime, set the environment + variable :envvar:`PYTHON_JIT=0 <PYTHON_JIT>`. + + ``--enable-experimental-jit=no`` is the default behavior if the option is not + provided, and ``--enable-experimental-jit`` is shorthand for + ``--enable-experimental-jit=yes``. See :file:`Tools/jit/README.md` for more + information, including how to install the necessary build-time dependencies. .. note:: diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index 57c6062ee43..74d6db5d7d1 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -529,6 +529,25 @@ depending on whether it was installed from python.org or through the Windows Store. Attempting to run the executable directly from Program Files is not recommended. +To programmatically install or uninstall the MSIX without using your +distribution platform's native support, the `Add-AppxPackage +<https://learn.microsoft.com/powershell/module/appx/add-appxpackage>`_ and +`Remove-AppxPackage <https://learn.microsoft.com/powershell/module/appx/remove-appxpackage>`_ +PowerShell cmdlets are simplest to use: + +.. code:: + + $> Add-AppxPackage C:\Downloads\python-manager-25.0.msix + ... + $> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage + +The native APIs for package management may be found on the Windows +`PackageManager <https://learn.microsoft.com/uwp/api/windows.management.deployment.packagemanager>`_ +class. The :func:`!AddPackageAsync` method installs for the current user, or use +:func:`!StagePackageAsync` followed by :func:`!ProvisionPackageForAllUsersAsync` +to install the Python install manager for all users from the MSIX package. Users +will still need to install their own copies of Python itself, as there is no way +to trigger those installs without being a logged in user. .. _pymanager-admin-config: diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index fdccfb7deb1..9dbc07a34e2 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -1747,7 +1747,7 @@ Interpreter Changes ------------------------------- Two command-line options have been reserved for use by other Python -implementations. The :option:`-J` switch has been reserved for use by +implementations. The :option:`!-J` switch has been reserved for use by Jython for Jython-specific options, such as switches that are passed to the underlying JVM. :option:`-X` has been reserved for options specific to a particular implementation of Python such as CPython, diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 4b5515900ca..894f011ec86 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -2,7 +2,7 @@ What's new in Python 3.14 **************************** -:Editor: TBD +:Editor: Hugo van Kemenade .. Rules for maintenance: @@ -48,6 +48,10 @@ This article explains the new features in Python 3.14, compared to 3.13. For full details, see the :ref:`changelog <changelog>`. +.. seealso:: + + :pep:`745` -- Python 3.14 release schedule + .. note:: Prerelease users should be aware that this document is currently in draft @@ -61,22 +65,38 @@ Summary -- release highlights .. This section singles out the most important changes in Python 3.14. Brevity is key. +Python 3.14 beta is the pre-release of the next version of the Python +programming language, with a mix of changes to the language, the +implementation and the standard library. + +The biggest changes to the implementation include template strings (:pep:`750`), +deferred evaluation of annotations (:pep:`649`), +and a new type of interpreter that uses tail calls. + +The library changes include the addition of a new :mod:`!annotationlib` module +for introspecting and wrapping annotations (:pep:`649`), +a new :mod:`!compression.zstd` module for Zstandard support (:pep:`784`), +plus syntax highlighting in the REPL, +as well as the usual deprecations and removals, +and improvements in user-friendliness and correctness. .. PEP-sized items next. * :ref:`PEP 649: deferred evaluation of annotations <whatsnew314-pep649>` * :ref:`PEP 741: Python Configuration C API <whatsnew314-pep741>` -* :ref:`PEP 750: Template Strings <whatsnew314-pep750>` +* :ref:`PEP 750: Template strings <whatsnew314-pep750>` * :ref:`PEP 758: Allow except and except* expressions without parentheses <whatsnew314-pep758>` * :ref:`PEP 761: Discontinuation of PGP signatures <whatsnew314-pep761>` * :ref:`PEP 765: Disallow return/break/continue that exit a finally block <whatsnew314-pep765>` * :ref:`PEP 768: Safe external debugger interface for CPython <whatsnew314-pep768>` +* :ref:`PEP 784: Adding Zstandard to the standard library <whatsnew314-pep784>` * :ref:`A new type of interpreter <whatsnew314-tail-call>` * :ref:`Syntax highlighting in PyREPL <whatsnew314-pyrepl-highlighting>`, and color output in :ref:`unittest <whatsnew314-color-unittest>`, :ref:`argparse <whatsnew314-color-argparse>`, :ref:`json <whatsnew314-color-json>` and :ref:`calendar <whatsnew314-color-calendar>` CLIs +* :ref:`Binary releases for the experimental just-in-time compiler <whatsnew314-jit-compiler>` Incompatible changes @@ -104,7 +124,7 @@ New features .. _whatsnew314-pep750: -PEP 750: Template Strings +PEP 750: Template strings ------------------------- Template string literals (t-strings) are a generalization of f-strings, @@ -166,12 +186,14 @@ With this in place, developers can write template systems to sanitize SQL, make safe shell operations, improve logging, tackle modern ideas in web development (HTML, CSS, and so on), and implement lightweight, custom business DSLs. -See :pep:`750` for more details. - (Contributed by Jim Baker, Guido van Rossum, Paul Everitt, Koudai Aono, Lysandros Nikolaou, Dave Peck, Adam Turner, Jelle Zijlstra, Bénédikt Tran, and Pablo Galindo Salgado in :gh:`132661`.) +.. seealso:: + :pep:`750`. + + .. _whatsnew314-pep768: PEP 768: Safe external debugger interface for CPython @@ -227,10 +249,57 @@ A key implementation detail is that the interface piggybacks on the interpreter' loop and safe points, ensuring zero overhead during normal execution while providing a reliable way for external processes to coordinate debugging operations. -See :pep:`768` for more details. - (Contributed by Pablo Galindo Salgado, Matt Wozniski, and Ivona Stojanovic in :gh:`131591`.) +.. seealso:: + :pep:`768`. + + +.. _whatsnew314-pep784: + +PEP 784: Adding Zstandard to the standard library +------------------------------------------------- + +The new ``compression`` package contains modules :mod:`!compression.lzma`, +:mod:`!compression.bz2`, :mod:`!compression.gzip` and :mod:`!compression.zlib` +which re-export the :mod:`lzma`, :mod:`bz2`, :mod:`gzip` and :mod:`zlib` +modules respectively. The new import names under ``compression`` are the +canonical names for importing these compression modules going forward. However, +the existing modules names have not been deprecated. Any deprecation or removal +of the existing compression modules will occur no sooner than five years after +the release of 3.14. + +The new :mod:`!compression.zstd` module provides compression and decompression +APIs for the Zstandard format via bindings to `Meta's zstd library +<https://facebook.github.io/zstd/>`__. Zstandard is a widely adopted, highly +efficient, and fast compression format. In addition to the APIs introduced in +:mod:`!compression.zstd`, support for reading and writing Zstandard compressed +archives has been added to the :mod:`tarfile`, :mod:`zipfile`, and +:mod:`shutil` modules. + +Here's an example of using the new module to compress some data: + +.. code-block:: python + + from compression import zstd + import math + + data = str(math.pi).encode() * 20 + + compressed = zstd.compress(data) + + ratio = len(compressed) / len(data) + print(f"Achieved compression ratio of {ratio}") + +As can be seen, the API is similar to the APIs of the :mod:`!lzma` and +:mod:`!bz2` modules. + +(Contributed by Emma Harper Smith, Adam Turner, Gregory P. Smith, Tomas Roun, +Victor Stinner, and Rogdham in :gh:`132983`) + +.. seealso:: + :pep:`784`. + .. _whatsnew314-remote-pdb: @@ -250,12 +319,15 @@ attaching to a remote process that is blocked in a system call or waiting for I/O will only work once the next bytecode instruction is executed or when the process receives a signal. -This feature leverages :pep:`768` and the :func:`sys.remote_exec` function +This feature uses :pep:`768` and the :func:`sys.remote_exec` function to attach to the remote process and send the PDB commands to it. (Contributed by Matt Wozniski and Pablo Galindo in :gh:`131591`.) +.. seealso:: + :pep:`768`. + .. _whatsnew314-pep758: @@ -283,6 +355,9 @@ Check :pep:`758` for more details. (Contributed by Pablo Galindo and Brett Cannon in :gh:`131831`.) +.. seealso:: + :pep:`758`. + .. _whatsnew314-pep649: @@ -378,7 +453,7 @@ Improved error messages feature helps programmers quickly identify and fix common typing mistakes. For example: - .. code-block:: python + .. code-block:: pycon >>> whille True: ... pass @@ -419,7 +494,7 @@ Improved error messages error message prints the received number of values in more cases than before. (Contributed by Tushar Sadhwani in :gh:`122239`.) - .. code-block:: python + .. code-block:: pycon >>> x, y, z = 1, 2, 3, 4 Traceback (most recent call last): @@ -473,7 +548,7 @@ Improved error messages that the string may be intended to be part of the string. (Contributed by Pablo Galindo in :gh:`88535`.) - .. code-block:: python + .. code-block:: pycon >>> "The interesting object "The important object" is very important" Traceback (most recent call last): @@ -509,6 +584,9 @@ Improved error messages ^^^^^^ SyntaxError: cannot use subscript as import target +.. seealso:: + :pep:`649`. + .. _whatsnew314-pep741: @@ -715,9 +793,46 @@ in the :envvar:`PYTHONSTARTUP` script. (Contributed by Łukasz Langa in :gh:`131507`.) +.. _whatsnew314-jit-compiler: + +Binary releases for the experimental just-in-time compiler +---------------------------------------------------------- + +The official macOS and Windows release binaries now include an *experimental* +just-in-time (JIT) compiler. Although it is **not** recommended for production +use, it can be tested by setting :envvar:`PYTHON_JIT=1 <PYTHON_JIT>` as an +environment variable. Downstream source builds and redistributors can use the +:option:`--enable-experimental-jit=yes-off` configuration option for similar +behavior. + +The JIT is at an early stage and still in active development. As such, the +typical performance impact of enabling it can range from 10% slower to 20% +faster, depending on workload. To aid in testing and evaluation, a set of +introspection functions has been provided in the :data:`sys._jit` namespace. +:func:`sys._jit.is_available` can be used to determine if the current executable +supports JIT compilation, while :func:`sys._jit.is_enabled` can be used to tell +if JIT compilation has been enabled for the current process. + +Currently, the most significant missing functionality is that native debuggers +and profilers like ``gdb`` and ``perf`` are unable to unwind through JIT frames +(Python debuggers and profilers, like :mod:`pdb` or :mod:`profile`, continue to +work without modification). Free-threaded builds do not support JIT compilation. + +Please report any bugs or major performance regressions that you encounter! + +.. seealso:: :pep:`744` + + Other language changes ====================== +* The default :term:`interactive` shell now supports import autocompletion. + This means that typing ``import foo`` and pressing ``<tab>`` will suggest + modules starting with ``foo``. Similarly, typing ``from foo import b`` will + suggest submodules of ``foo`` starting with ``b``. Note that autocompletion + of module attributes is not currently supported. + (Contributed by Tomas Roun in :gh:`69605`.) + * The :func:`map` built-in now has an optional keyword-only *strict* flag like :func:`zip` to check that all the iterables are of equal length. (Contributed by Wannes Boeykens in :gh:`119793`.) @@ -778,9 +893,9 @@ Other language changes The testbed can also be used to run the test suite of projects other than CPython itself. (Contributed by Russell Keith-Magee in :gh:`127592`.) -* Three-argument :func:`pow` now try calling :meth:`~object.__rpow__` if necessary. - Previously it was only called in two-argument :func:`!pow` and the binary - power operator. +* Three-argument :func:`pow` now tries calling :meth:`~object.__rpow__` if + necessary. Previously it was only called in two-argument :func:`!pow` and the + binary power operator. (Contributed by Serhiy Storchaka in :gh:`130104`.) * Add a built-in implementation for HMAC (:rfc:`2104`) using formally verified @@ -789,27 +904,39 @@ Other language changes of HMAC is not available. (Contributed by Bénédikt Tran in :gh:`99108`.) +* The import time flag can now track modules that are already loaded ('cached'), + via the new :option:`-X importtime=2 <-X>`. + When such a module is imported, the ``self`` and ``cumulative`` times + are replaced by the string ``cached``. + Values above ``2`` for ``-X importtime`` are now reserved for future use. + (Contributed by Noah Kim and Adam Turner in :gh:`118655`.) + * When subclassing from a pure C type, the C slots for the new type are no longer replaced with a wrapped version on class creation if they are not explicitly overridden in the subclass. (Contributed by Tomasz Pytel in :gh:`132329`.) -* The command line option :option:`-c` now automatically dedents its code +* The command-line option :option:`-c` now automatically dedents its code argument before execution. The auto-dedentation behavior mirrors :func:`textwrap.dedent`. (Contributed by Jon Crall and Steven Sun in :gh:`103998`.) -* Improve error message when an object supporting the synchronous (resp. - asynchronous) context manager protocol is entered using :keyword:`async - with` (resp. :keyword:`with`) instead of :keyword:`with` (resp. - :keyword:`async with`). +* Improve error message when an object supporting the synchronous + context manager protocol is entered using :keyword:`async + with` instead of :keyword:`with`. + And vice versa with the asynchronous context manager protocol. (Contributed by Bénédikt Tran in :gh:`128398`.) +* :option:`!-J` is no longer a reserved flag for Jython_, + and now has no special meaning. + (Contributed by Adam Turner in :gh:`133336`.) + + .. _Jython: https://www.jython.org/ .. _whatsnew314-pep765: -PEP 765: Disallow return/break/continue that exit a finally block ------------------------------------------------------------------ +PEP 765: Disallow ``return``/``break``/``continue`` that exit a ``finally`` block +--------------------------------------------------------------------------------- The compiler emits a :exc:`SyntaxWarning` when a :keyword:`return`, :keyword:`break` or :keyword:`continue` statements appears where it exits a :keyword:`finally` block. @@ -844,10 +971,9 @@ argparse * Introduced the optional *color* parameter to :class:`argparse.ArgumentParser`, enabling color for help text. - This can be controlled via the :envvar:`PYTHON_COLORS` environment - variable as well as the canonical |NO_COLOR|_ - and |FORCE_COLOR|_ environment variables. - See also :ref:`using-on-controlling-color`. + This can be controlled by :ref:`environment variables + <using-on-controlling-color>`. Color has also been enabled for help in the + :ref:`stdlib CLIs <library-cmdline>` which use :mod:`!argparse`. (Contributed by Hugo van Kemenade in :gh:`130645`.) @@ -864,12 +990,17 @@ ast (Contributed by Irit Katriel in :gh:`123958`.) * The ``repr()`` output for AST nodes now includes more information. - (Contributed by Tomas R in :gh:`116022`.) + (Contributed by Tomas Roun in :gh:`116022`.) * :func:`ast.parse`, when called with an AST as input, now always verifies that the root node type is appropriate. (Contributed by Irit Katriel in :gh:`130139`.) +* Add new ``--feature-version``, ``--optimize``, ``--show-empty`` options to + command-line interface. + (Contributed by Semyon Moroz in :gh:`133367`.) + + bdb --- @@ -884,10 +1015,8 @@ calendar * By default, today's date is highlighted in color in :mod:`calendar`'s :ref:`command-line <calendar-cli>` text output. - This can be controlled via the :envvar:`PYTHON_COLORS` environment - variable as well as the canonical |NO_COLOR|_ - and |FORCE_COLOR|_ environment variables. - See also :ref:`using-on-controlling-color`. + This can be controlled by :ref:`environment variables + <using-on-controlling-color>`. (Contributed by Hugo van Kemenade in :gh:`128317`.) @@ -895,7 +1024,7 @@ concurrent.futures ------------------ * Add :class:`~concurrent.futures.InterpreterPoolExecutor`, - which exposes "subinterpreters (multiple Python interpreters in the + which exposes "subinterpreters" (multiple Python interpreters in the same process) to Python code. This is separate from the proposed API in :pep:`734`. (Contributed by Eric Snow in :gh:`124548`.) @@ -974,7 +1103,7 @@ ctypes :class:`~ctypes.c_double_complex` and :class:`~ctypes.c_longdouble_complex`, are now available if both the compiler and the ``libffi`` library support complex C types. - (Contributed by Sergey B Kirpichev in :gh:`61103`). + (Contributed by Sergey B Kirpichev in :gh:`61103`.) * Add :func:`ctypes.util.dllist` for listing the shared libraries loaded by the current process. @@ -984,7 +1113,7 @@ ctypes (``_pointer_type_cache``) to the :attr:`ctypes._CData.__pointer_type__` attribute of the corresponding :mod:`ctypes` types. This will stop the cache from growing without limits in some situations. - (Contributed by Sergey Miryanov in :gh:`100926`). + (Contributed by Sergey Miryanov in :gh:`100926`.) * The :class:`ctypes.py_object` type now supports subscription, making it a :term:`generic type`. @@ -1101,12 +1230,33 @@ getopt (Contributed by Serhiy Storchaka in :gh:`126390`.) +getpass +------- + +* Support keyboard feedback by :func:`getpass.getpass` via the keyword-only + optional argument ``echo_char``. Placeholder characters are rendered whenever + a character is entered, and removed when a character is deleted. + (Contributed by Semyon Moroz in :gh:`77065`.) + + graphlib -------- * Allow :meth:`graphlib.TopologicalSorter.prepare` to be called more than once as long as sorting has not started. - (Contributed by Daniel Pope in :gh:`130914`) + (Contributed by Daniel Pope in :gh:`130914`.) + + +heapq +----- + +* Add functions for working with max-heaps: + + * :func:`heapq.heapify_max`, + * :func:`heapq.heappush_max`, + * :func:`heapq.heappop_max`, + * :func:`heapq.heapreplace_max` + * :func:`heapq.heappushpop_max` hmac @@ -1187,11 +1337,10 @@ json .. _whatsnew314-color-json: -* By default, the output of the :ref:`JSON command-line interface <json-commandline>` - is highlighted in color. This can be controlled via the - :envvar:`PYTHON_COLORS` environment variable as well as the canonical - |NO_COLOR|_ and |FORCE_COLOR|_ environment variables. See also - :ref:`using-on-controlling-color`. +* By default, the output of the :ref:`JSON command-line interface + <json-commandline>` is highlighted in color. + This can be controlled by :ref:`environment variables + <using-on-controlling-color>`. (Contributed by Tomas Roun in :gh:`131952`.) linecache @@ -1327,9 +1476,9 @@ multiprocessing * The :ref:`multiprocessing proxy objects <multiprocessing-proxy_objects>` for *list* and *dict* types gain previously overlooked missing methods: - * :meth:`!clear` and :meth:`!copy` for proxies of :class:`list`. + * :meth:`!clear` and :meth:`!copy` for proxies of :class:`list` * :meth:`~dict.fromkeys`, ``reversed(d)``, ``d | {}``, ``{} | d``, - ``d |= {'b': 2}`` for proxies of :class:`dict`. + ``d |= {'b': 2}`` for proxies of :class:`dict` (Contributed by Roy Hyunjin Han for :gh:`103134`.) @@ -1339,9 +1488,9 @@ multiprocessing (Contributed by Mingyu Park in :gh:`129949`.) * Add :func:`multiprocessing.Process.interrupt` which terminates the child - process by sending :py:const:`~signal.SIGINT`. This enables "finally" clauses - and printing stack trace for the terminated process. - (Contributed by Artem Pulkin in :gh:`131913`.) + process by sending :py:const:`~signal.SIGINT`. This enables + :keyword:`finally` clauses to print a stack trace for the terminated + process. (Contributed by Artem Pulkin in :gh:`131913`.) operator -------- @@ -1421,6 +1570,11 @@ pdb fill in a 4-space indentation now, instead of inserting a ``\t`` character. (Contributed by Tian Gao in :gh:`130471`.) +* Auto-indent is introduced in :mod:`pdb` multi-line input. It will either + keep the indentation of the last line or insert a 4-space indentation when + it detects a new code block. + (Contributed by Tian Gao in :gh:`133350`.) + * ``$_asynctask`` is added to access the current asyncio task if applicable. (Contributed by Tian Gao in :gh:`124367`.) @@ -1436,6 +1590,11 @@ pdb function. (Contributed by Tian Gao in :gh:`132576`.) +* Source code displayed in :mod:`pdb` will be syntax-highlighted. This feature + can be controlled using the same methods as PyREPL, in addition to the newly + added ``colorize`` argument of :class:`pdb.Pdb`. + (Contributed by Tian Gao and Łukasz Langa in :gh:`133355`.) + pickle ------ @@ -1481,7 +1640,7 @@ socket :const:`~socket.BTPROTO_HCI` on Linux. (Contributed by Serhiy Storchaka in :gh:`70145`.) * Accept an integer as the address for - :const:`~socket.BTPROTO_HCI` on Linux + :const:`~socket.BTPROTO_HCI` on Linux. (Contributed by Serhiy Storchaka in :gh:`132099`.) * Return *cid* in :meth:`~socket.socket.getsockname` for :const:`~socket.BTPROTO_L2CAP`. @@ -1560,8 +1719,8 @@ threading tkinter ------- -* Make tkinter widget methods :meth:`!after` and :meth:`!after_idle` accept - arguments passed by keyword. +* Make :mod:`tkinter` widget methods :meth:`!after` and :meth:`!after_idle` + accept arguments passed by keyword. (Contributed by Zhikang Yan in :gh:`126899`.) * Add ability to specify name for :class:`!tkinter.OptionMenu` and @@ -1639,10 +1798,8 @@ unittest -------- * :mod:`unittest` output is now colored by default. - This can be controlled via the :envvar:`PYTHON_COLORS` environment - variable as well as the canonical |NO_COLOR|_ - and |FORCE_COLOR|_ environment variables. - See also :ref:`using-on-controlling-color`. + This can be controlled by :ref:`environment variables + <using-on-controlling-color>`. (Contributed by Hugo van Kemenade in :gh:`127221`.) * unittest discovery supports :term:`namespace package` as start @@ -1681,9 +1838,11 @@ urllib - Accept a complete URL when the new *require_scheme* argument is set to true. - - Discard URL authorities that resolve to a local IP address. - - Raise :exc:`~urllib.error.URLError` if a URL authority doesn't resolve - to a local IP address, except on Windows where we return a UNC path. + - Discard URL authority if it matches the local hostname. + - Discard URL authority if it resolves to a local IP address when the new + *resolve_host* argument is set to true. + - Raise :exc:`~urllib.error.URLError` if a URL authority isn't local, + except on Windows where we return a UNC path as before. In :func:`urllib.request.pathname2url`: @@ -1870,11 +2029,17 @@ Deprecated (Contributed by Inada Naoki in :gh:`133036`.) * :mod:`ctypes`: - Calling :func:`ctypes.POINTER` on a string is deprecated. - Use :ref:`ctypes-incomplete-types` for self-referential structures. - Also, the internal ``ctypes._pointer_type_cache`` is deprecated. - See :func:`ctypes.POINTER` for updated implementation details. - (Contributed by Sergey Myrianov in :gh:`100926`.) + + * On non-Windows platforms, setting :attr:`.Structure._pack_` to use a + MSVC-compatible default memory layout is deprecated in favor of setting + :attr:`.Structure._layout_` to ``'ms'``. + (Contributed by Petr Viktorin in :gh:`131747`.) + + * Calling :func:`ctypes.POINTER` on a string is deprecated. + Use :ref:`ctypes-incomplete-types` for self-referential structures. + Also, the internal ``ctypes._pointer_type_cache`` is deprecated. + See :func:`ctypes.POINTER` for updated implementation details. + (Contributed by Sergey Myrianov in :gh:`100926`.) * :mod:`functools`: Calling the Python implementation of :func:`functools.reduce` with *function* @@ -1943,6 +2108,8 @@ Deprecated .. include:: ../deprecations/pending-removal-in-3.17.rst +.. include:: ../deprecations/pending-removal-in-3.19.rst + .. include:: ../deprecations/pending-removal-in-future.rst Removed @@ -2038,7 +2205,7 @@ asyncio asyncio.run(main()) - If you need to start something, e.g. a server listening on a socket + If you need to start something, for example, a server listening on a socket and then run forever, use :func:`asyncio.run` and an :class:`asyncio.Event`. @@ -2213,14 +2380,8 @@ Others integer must implement either :meth:`~object.__int__` or :meth:`~object.__index__`. (Contributed by Mark Dickinson in :gh:`119743`.) -* The default :term:`interactive` shell now supports import autocompletion. - This means that typing ``import foo`` and pressing ``<tab>`` will suggest - modules starting with ``foo``. Similarly, typing ``from foo import b`` will - suggest submodules of ``foo`` starting with ``b``. Note that autocompletion - of module attributes is not currently supported. - (Contributed by Tomas Roun in :gh:`69605`.) -CPython Bytecode Changes +CPython bytecode changes ======================== * Replaced the opcode ``BINARY_SUBSCR`` by :opcode:`BINARY_OP` with oparg ``NB_SUBSCR``. @@ -2361,12 +2522,12 @@ New features * Add a new import and export API for Python :class:`int` objects (:pep:`757`): - * :c:func:`PyLong_GetNativeLayout`; - * :c:func:`PyLong_Export`; - * :c:func:`PyLong_FreeExport`; - * :c:func:`PyLongWriter_Create`; - * :c:func:`PyLongWriter_Finish`; - * :c:func:`PyLongWriter_Discard`. + * :c:func:`PyLong_GetNativeLayout` + * :c:func:`PyLong_Export` + * :c:func:`PyLong_FreeExport` + * :c:func:`PyLongWriter_Create` + * :c:func:`PyLongWriter_Finish` + * :c:func:`PyLongWriter_Discard` (Contributed by Sergey B Kirpichev and Victor Stinner in :gh:`102471`.) @@ -2427,6 +2588,10 @@ New features be used in some cases as a replacement for checking if :c:func:`Py_REFCNT` is ``1`` for Python objects passed as arguments to C API functions. +* Add :c:func:`PyUnstable_Object_IsUniquelyReferenced` as a replacement for + ``Py_REFCNT(op) == 1`` on :term:`free threaded <free threading>` builds. + (Contributed by Peter Bierma in :gh:`133140`.) + Limited C API changes --------------------- @@ -2474,24 +2639,24 @@ Porting to Python 3.14 * Private functions promoted to public C APIs: - * ``_PyBytes_Join()``: :c:func:`PyBytes_Join`. - * ``_PyLong_IsNegative()``: :c:func:`PyLong_IsNegative`. - * ``_PyLong_IsPositive()``: :c:func:`PyLong_IsPositive`. - * ``_PyLong_IsZero()``: :c:func:`PyLong_IsZero`. - * ``_PyLong_Sign()``: :c:func:`PyLong_GetSign`. - * ``_PyUnicodeWriter_Dealloc()``: :c:func:`PyUnicodeWriter_Discard`. - * ``_PyUnicodeWriter_Finish()``: :c:func:`PyUnicodeWriter_Finish`. - * ``_PyUnicodeWriter_Init()``: use :c:func:`PyUnicodeWriter_Create`. - * ``_PyUnicodeWriter_Prepare()``: (no replacement). - * ``_PyUnicodeWriter_PrepareKind()``: (no replacement). - * ``_PyUnicodeWriter_WriteChar()``: :c:func:`PyUnicodeWriter_WriteChar`. - * ``_PyUnicodeWriter_WriteStr()``: :c:func:`PyUnicodeWriter_WriteStr`. - * ``_PyUnicodeWriter_WriteSubstring()``: :c:func:`PyUnicodeWriter_WriteSubstring`. - * ``_PyUnicode_EQ()``: :c:func:`PyUnicode_Equal`. - * ``_PyUnicode_Equal()``: :c:func:`PyUnicode_Equal`. - * ``_Py_GetConfig()``: :c:func:`PyConfig_Get` and :c:func:`PyConfig_GetInt`. - * ``_Py_HashBytes()``: :c:func:`Py_HashBuffer`. - * ``_Py_fopen_obj()``: :c:func:`Py_fopen`. + * ``_PyBytes_Join()``: :c:func:`PyBytes_Join` + * ``_PyLong_IsNegative()``: :c:func:`PyLong_IsNegative` + * ``_PyLong_IsPositive()``: :c:func:`PyLong_IsPositive` + * ``_PyLong_IsZero()``: :c:func:`PyLong_IsZero` + * ``_PyLong_Sign()``: :c:func:`PyLong_GetSign` + * ``_PyUnicodeWriter_Dealloc()``: :c:func:`PyUnicodeWriter_Discard` + * ``_PyUnicodeWriter_Finish()``: :c:func:`PyUnicodeWriter_Finish` + * ``_PyUnicodeWriter_Init()``: use :c:func:`PyUnicodeWriter_Create` + * ``_PyUnicodeWriter_Prepare()``: (no replacement) + * ``_PyUnicodeWriter_PrepareKind()``: (no replacement) + * ``_PyUnicodeWriter_WriteChar()``: :c:func:`PyUnicodeWriter_WriteChar` + * ``_PyUnicodeWriter_WriteStr()``: :c:func:`PyUnicodeWriter_WriteStr` + * ``_PyUnicodeWriter_WriteSubstring()``: :c:func:`PyUnicodeWriter_WriteSubstring` + * ``_PyUnicode_EQ()``: :c:func:`PyUnicode_Equal` + * ``_PyUnicode_Equal()``: :c:func:`PyUnicode_Equal` + * ``_Py_GetConfig()``: :c:func:`PyConfig_Get` and :c:func:`PyConfig_GetInt` + * ``_Py_HashBytes()``: :c:func:`Py_HashBuffer` + * ``_Py_fopen_obj()``: :c:func:`Py_fopen` The `pythoncapi-compat project`_ can be used to get most of these new functions on Python 3.13 and older. |