diff options
Diffstat (limited to 'Doc')
42 files changed, 594 insertions, 214 deletions
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 0b05e868917..3bbc990b632 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -274,7 +274,7 @@ small to receive the value. Convert a Python integer to a C :c:expr:`unsigned long` without overflow checking. - .. versionchanged:: next + .. versionchanged:: 3.14 Use :meth:`~object.__index__` if available. ``L`` (:class:`int`) [long long] @@ -284,7 +284,7 @@ small to receive the value. Convert a Python integer to a C :c:expr:`unsigned long long` without overflow checking. - .. versionchanged:: next + .. versionchanged:: 3.14 Use :meth:`~object.__index__` if available. ``n`` (:class:`int`) [:c:type:`Py_ssize_t`] @@ -380,10 +380,10 @@ Other objects The *converter* for the ``O&`` format unit in *items* must not store a borrowed buffer or a borrowed reference. - .. versionchanged:: next + .. versionchanged:: 3.14 :class:`str` and :class:`bytearray` objects no longer accepted as a sequence. - .. deprecated:: next + .. deprecated:: 3.14 Non-tuple sequences are deprecated if *items* contains format units which store a borrowed buffer or a borrowed reference. @@ -396,7 +396,7 @@ Other objects If the argument is not ``None``, it is parsed according to the specified format unit. - .. versionadded:: next + .. versionadded:: 3.14 A few other characters have a meaning in a format string. These may not occur inside nested parentheses. They are: diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index bc5b236393b..e1931655618 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:: 3.14 + + Added support for ``import_time = 2`` + .. c:member:: int inspect Enter interactive mode after executing a script or a command. diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index 661d6c290f6..7d64a02358a 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -626,7 +626,7 @@ which, when run, will produce: of each message with the handler's level, and only passes a message to a handler if it's appropriate to do so. -.. versionchanged:: next +.. versionchanged:: 3.14 The :class:`QueueListener` can be started (and stopped) via the :keyword:`with` statement. For example: diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index feccc635ff7..29396c7a036 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -641,7 +641,7 @@ keyword argument:: >>> parser = argparse.ArgumentParser(description='Process some integers.') >>> parser.color = True -.. versionadded:: next +.. versionadded:: 3.14 The add_argument() method diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index c9ae0abdd66..ca9a6b0712c 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -2577,21 +2577,21 @@ The following options are accepted: Python version in the format 3.x (for example, 3.10). Defaults to the current version of the interpreter. - .. versionadded:: next + .. versionadded:: 3.14 .. option:: -O <level> --optimize <level> Optimization level for parser. Defaults to no optimization. - .. versionadded:: next + .. versionadded:: 3.14 .. option:: --show-empty Show empty lists and fields that are ``None``. Defaults to not showing empty objects. - .. versionadded:: next + .. versionadded:: 3.14 If :file:`infile` is specified its contents are parsed to AST and dumped diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index e25f6e52efc..21f7d0547af 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -388,7 +388,7 @@ Creating Futures and Tasks .. versionchanged:: 3.11 Added the *context* parameter. - .. versionchanged:: next + .. versionchanged:: 3.14 Added the *eager_start* parameter. .. method:: loop.set_task_factory(factory) diff --git a/Doc/library/audit_events.rst b/Doc/library/audit_events.rst index d2377a38d78..73a58092024 100644 --- a/Doc/library/audit_events.rst +++ b/Doc/library/audit_events.rst @@ -48,5 +48,5 @@ public API of CPython: | ctypes.PyObj_FromPtr | ``obj`` | +----------------------------+-------------------------------------------+ -.. versionadded:: next +.. versionadded:: 3.14 The ``_posixsubprocess.fork_exec`` internal audit event. 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/codecs.rst b/Doc/library/codecs.rst index 14f6547e4e0..86511602fa5 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -208,7 +208,7 @@ wider range of codecs when working with binary files: .. versionchanged:: 3.11 The ``'U'`` mode has been removed. - .. deprecated:: next + .. deprecated:: 3.14 :func:`codecs.open` has been superseded by :func:`open`. diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 1b78b33b69f..5b733d5321e 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2358,7 +2358,7 @@ Data types :func:`POINTER` for corresponding ctypes data type. If a pointer type was not yet created, the attribute is missing. - .. versionadded:: next + .. versionadded:: 3.14 Common instance variables of ctypes data types: @@ -2756,7 +2756,7 @@ fields, or any other data types containing pointer type fields. This is only implemented for the MSVC-compatible memory layout. - .. deprecated-removed:: next 3.19 + .. deprecated-removed:: 3.14 3.19 For historical reasons, if :attr:`!_pack_` is non-zero, the MSVC-compatible layout will be used by default. @@ -2799,7 +2799,7 @@ fields, or any other data types containing pointer type fields. :attr:`!_layout_` must already be defined when :attr:`~Structure._fields_` is assigned, otherwise it will have no effect. - .. versionadded:: next + .. versionadded:: 3.14 .. attribute:: _anonymous_ diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 4bccfdde664..137504c51b4 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -80,7 +80,7 @@ The module :mod:`curses` defines the following functions: * Change the definition of the color-pair ``0`` to ``(fg, bg)``. - .. versionadded:: next + .. versionadded:: 3.14 .. function:: baudrate() diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index deaad059ef8..f53c1f34670 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -1037,7 +1037,7 @@ function to temporarily change the active context. IEEE interchange formats. The argument must be a multiple of 32 and less than :const:`IEEE_CONTEXT_MAX_BITS`. - .. versionadded:: next + .. versionadded:: 3.14 New contexts can also be created using the :class:`Context` constructor described below. In addition, the module provides three pre-made contexts: diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 4b391ba020a..bb72032891e 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -436,7 +436,7 @@ The following exceptions are the exceptions that are usually raised. .. versionadded:: 3.13 Previously, a plain :exc:`RuntimeError` was raised. - .. versionchanged:: next + .. versionchanged:: 3.14 :meth:`threading.Thread.join` can now raise this exception. diff --git a/Doc/library/faulthandler.rst b/Doc/library/faulthandler.rst index e34b067aea5..5058b85bffb 100644 --- a/Doc/library/faulthandler.rst +++ b/Doc/library/faulthandler.rst @@ -69,7 +69,7 @@ Dumping the traceback Dumping the C stack ------------------- -.. versionadded:: next +.. versionadded:: 3.14 .. function:: dump_c_stack(file=sys.stderr) @@ -130,7 +130,7 @@ Fault handler state Only the current thread is dumped if the :term:`GIL` is disabled to prevent the risk of data races. - .. versionchanged:: next + .. versionchanged:: 3.14 The dump now displays the C stack trace if *c_stack* is true. .. function:: disable() diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst index b4ea3e7e31b..c8ce86cc7af 100644 --- a/Doc/library/fcntl.rst +++ b/Doc/library/fcntl.rst @@ -79,7 +79,7 @@ descriptor. On macOS and NetBSD, the :mod:`!fcntl` module exposes the ``F_GETNOSIGPIPE`` and ``F_SETNOSIGPIPE`` constant. -.. versionchanged:: next +.. versionchanged:: 3.14 On Linux >= 6.1, the :mod:`!fcntl` module exposes the ``F_DUPFD_QUERY`` to query a file descriptor pointing to the same file. @@ -121,7 +121,7 @@ The module defines the following functions: .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl - .. versionchanged:: next + .. versionchanged:: 3.14 Add support of arbitrary :term:`bytes-like objects <bytes-like object>`, not only :class:`bytes`. @@ -181,7 +181,7 @@ The module defines the following functions: .. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl - .. versionchanged:: next + .. versionchanged:: 3.14 The GIL is always released during a system call. System calls failing with EINTR are automatically retried. diff --git a/Doc/library/getpass.rst b/Doc/library/getpass.rst index 3b5296f9ec6..0fb0fc88683 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:: 3.14 + 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/hashlib.rst b/Doc/library/hashlib.rst index ff15a08a792..bb2d2fad23b 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -302,7 +302,7 @@ a file or file-like object. .. versionadded:: 3.11 - .. versionchanged:: next + .. versionchanged:: 3.14 Now raises a :exc:`BlockingIOError` if the file is opened in blocking mode. Previously, spurious null bytes were added to the digest. diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index 2bd0162a982..922ba0c8aa4 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -105,7 +105,7 @@ For max-heaps, the following functions are provided: Transform list *x* into a max-heap, in-place, in linear time. - .. versionadded:: next + .. versionadded:: 3.14 .. function:: heappush_max(heap, item) @@ -113,7 +113,7 @@ For max-heaps, the following functions are provided: Push the value *item* onto the max-heap *heap*, maintaining the max-heap invariant. - .. versionadded:: next + .. versionadded:: 3.14 .. function:: heappop_max(heap) @@ -122,7 +122,7 @@ For max-heaps, the following functions are provided: 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 + .. versionadded:: 3.14 .. function:: heappushpop_max(heap, item) @@ -132,7 +132,7 @@ For max-heaps, the following functions are provided: The combined action runs more efficiently than :func:`heappush_max` followed by a separate call to :func:`heappop_max`. - .. versionadded:: next + .. versionadded:: 3.14 .. function:: heapreplace_max(heap, item) @@ -145,7 +145,7 @@ For max-heaps, the following functions are provided: The value returned may be smaller than the *item* added. Refer to the analogous function :func:`heapreplace` for detailed usage notes. - .. versionadded:: next + .. versionadded:: 3.14 The module also offers three general purpose functions based on heaps. diff --git a/Doc/library/html.parser.rst b/Doc/library/html.parser.rst index 6d433b5a04f..dd67fc34e85 100644 --- a/Doc/library/html.parser.rst +++ b/Doc/library/html.parser.rst @@ -43,7 +43,9 @@ Example HTML Parser Application As a basic example, below is a simple HTML parser that uses the :class:`HTMLParser` class to print out start tags, end tags, and data -as they are encountered:: +as they are encountered: + +.. testcode:: from html.parser import HTMLParser @@ -63,7 +65,7 @@ as they are encountered:: The output will then be: -.. code-block:: none +.. testoutput:: Encountered a start tag: html Encountered a start tag: head @@ -230,7 +232,9 @@ Examples -------- The following class implements a parser that will be used to illustrate more -examples:: +examples: + +.. testcode:: from html.parser import HTMLParser from html.entities import name2codepoint @@ -266,13 +270,17 @@ examples:: parser = MyHTMLParser() -Parsing a doctype:: +Parsing a doctype: + +.. doctest:: >>> parser.feed('<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" ' ... '"http://www.w3.org/TR/html4/strict.dtd">') Decl : DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd" -Parsing an element with a few attributes and a title:: +Parsing an element with a few attributes and a title: + +.. doctest:: >>> parser.feed('<img src="python-logo.png" alt="The Python logo">') Start tag: img @@ -285,7 +293,9 @@ Parsing an element with a few attributes and a title:: End tag : h1 The content of ``script`` and ``style`` elements is returned as is, without -further parsing:: +further parsing: + +.. doctest:: >>> parser.feed('<style type="text/css">#python { color: green }</style>') Start tag: style @@ -300,16 +310,25 @@ further parsing:: Data : alert("<strong>hello!</strong>"); End tag : script -Parsing comments:: +Parsing comments: + +.. doctest:: - >>> parser.feed('<!-- a comment -->' + >>> parser.feed('<!--a comment-->' ... '<!--[if IE 9]>IE-specific content<![endif]-->') - Comment : a comment + Comment : a comment Comment : [if IE 9]>IE-specific content<![endif] Parsing named and numeric character references and converting them to the -correct char (note: these 3 references are all equivalent to ``'>'``):: +correct char (note: these 3 references are all equivalent to ``'>'``): +.. doctest:: + + >>> parser = MyHTMLParser() + >>> parser.feed('>>>') + Data : >>> + + >>> parser = MyHTMLParser(convert_charrefs=False) >>> parser.feed('>>>') Named ent: > Num ent : > @@ -317,18 +336,22 @@ correct char (note: these 3 references are all equivalent to ``'>'``):: Feeding incomplete chunks to :meth:`~HTMLParser.feed` works, but :meth:`~HTMLParser.handle_data` might be called more than once -(unless *convert_charrefs* is set to ``True``):: +(unless *convert_charrefs* is set to ``True``): - >>> for chunk in ['<sp', 'an>buff', 'ered ', 'text</s', 'pan>']: +.. doctest:: + + >>> for chunk in ['<sp', 'an>buff', 'ered', ' text</s', 'pan>']: ... parser.feed(chunk) ... Start tag: span Data : buff Data : ered - Data : text + Data : text End tag : span -Parsing invalid HTML (e.g. unquoted attributes) also works:: +Parsing invalid HTML (e.g. unquoted attributes) also works: + +.. doctest:: >>> parser.feed('<p><a class=link href=#main>tag soup</p ></a>') Start tag: p diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst index 72312b512a5..63ef533e82c 100644 --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -1148,7 +1148,7 @@ possible, while any potentially slow operations (such as sending an email via .. versionchanged:: 3.5 The ``respect_handler_level`` argument was added. - .. versionchanged:: next + .. versionchanged:: 3.14 :class:`QueueListener` can now be used as a context manager via :keyword:`with`. When entering the context, the listener is started. When exiting the context, the listener is stopped. @@ -1186,7 +1186,7 @@ possible, while any potentially slow operations (such as sending an email via This starts up a background thread to monitor the queue for LogRecords to process. - .. versionchanged:: next + .. versionchanged:: 3.14 Raises :exc:`RuntimeError` if called and the listener is already running. diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index e44142a8ed3..6c43d5fe166 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -687,7 +687,7 @@ The :mod:`multiprocessing` package mostly replicates the API of the :attr:`exitcode` you may simply catch :exc:`KeyboardInterrupt` and call ``exit(your_code)``. - .. versionadded:: next + .. versionadded:: 3.14 .. method:: terminate() diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst index acb91812818..7d7692dea5c 100644 --- a/Doc/library/pathlib.rst +++ b/Doc/library/pathlib.rst @@ -871,7 +871,7 @@ conforming to :rfc:`8089`. .. versionadded:: 3.13 - .. versionchanged:: next + .. versionchanged:: 3.14 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 diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 0ee2d68bcbe..eb3b1e5549c 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -667,7 +667,7 @@ character ``'$'``. ``\z`` Matches only at the end of the string. - .. versionadded:: next + .. versionadded:: 3.14 ``\Z`` The same as ``\z``. For compatibility with old Python versions. diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst index 29e560cbc7a..f649fce5efc 100644 --- a/Doc/library/readline.rst +++ b/Doc/library/readline.rst @@ -76,7 +76,7 @@ The following functions relate to the init file and user configuration: if given, and :code:`"<readline_init_file>"` otherwise, regardless of which file the library resolves. - .. versionchanged:: next + .. versionchanged:: 3.14 The auditing event was added. @@ -119,7 +119,7 @@ The following functions operate on a history file: and raises an :ref:`auditing event <auditing>` ``open`` with the file name if given and :code:`"~/.history"` otherwise. - .. versionchanged:: next + .. versionchanged:: 3.14 The auditing event was added. @@ -131,7 +131,7 @@ The following functions operate on a history file: :ref:`auditing event <auditing>` ``open`` with the file name if given and :code:`"~/.history"` otherwise. - .. versionchanged:: next + .. versionchanged:: 3.14 The auditing event was added. @@ -146,7 +146,7 @@ The following functions operate on a history file: .. versionadded:: 3.5 - .. versionchanged:: next + .. versionchanged:: 3.14 The auditing event was added. diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 3c8dc26138f..8fd5187e3a4 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -170,7 +170,7 @@ created. Socket addresses are represented as follows: .. versionchanged:: 3.13.3 FreeBSD support added. - .. versionchanged:: next + .. versionchanged:: 3.14 Added ``channel`` field. ``device_id`` not packed in a tuple is now accepted. @@ -178,7 +178,7 @@ created. Socket addresses are represented as follows: the Bluetooth address as a string or a :class:`bytes` object. (ex. ``'12:23:34:45:56:67'`` or ``b'12:23:34:45:56:67'``) - .. versionchanged:: next + .. versionchanged:: 3.14 FreeBSD support added. - :const:`AF_ALG` is a Linux-only socket based interface to Kernel @@ -498,7 +498,7 @@ Constants .. versionchanged:: 3.11 NetBSD support was added. - .. versionchanged:: next + .. versionchanged:: 3.14 Restored missing ``CAN_RAW_ERR_FILTER`` on Linux. .. data:: CAN_BCM @@ -709,7 +709,7 @@ Constants :const:`!SO_BTH_*` are only available on Windows. Other constants may be available on Linux and various BSD platforms. - .. versionadded:: next + .. versionadded:: 3.14 .. data:: HCI_FILTER HCI_TIME_STAMP @@ -720,7 +720,7 @@ Constants Option names for use with :const:`BTPROTO_HCI`. Availability and format of the option values depend on platform. - .. versionchanged:: next + .. versionchanged:: 3.14 Added :const:`!SO_HCI_EVT_FILTER` and :const:`!SO_HCI_PKT_FILTER` on NetBSD and DragonFly BSD. Added :const:`!HCI_DATA_DIR` on FreeBSD, NetBSD and DragonFly BSD. @@ -732,7 +732,7 @@ Constants .. availability:: Linux - .. versionadded:: next + .. versionadded:: 3.14 .. data:: HCI_CHANNEL_RAW HCI_CHANNEL_USER @@ -744,7 +744,7 @@ Constants .. availability:: Linux - .. versionadded:: next + .. versionadded:: 3.14 .. data:: AF_QIPCRTR diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 39aaa5da078..61d39a6671c 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -4823,7 +4823,13 @@ can be used interchangeably to index the same dictionary entry. being added is already present, the value from the keyword argument replaces the value from the positional argument. - To illustrate, the following examples all return a dictionary equal to + Providing keyword arguments as in the first example only works for keys that + are valid Python identifiers. Otherwise, any valid keys can be used. + + Dictionaries compare equal if and only if they have the same ``(key, + value)`` pairs (regardless of ordering). Order comparisons ('<', '<=', '>=', '>') raise + :exc:`TypeError`. To illustrate dictionary creation and equality, + the following examples all return a dictionary equal to ``{"one": 1, "two": 2, "three": 3}``:: >>> a = dict(one=1, two=2, three=3) @@ -4838,6 +4844,27 @@ can be used interchangeably to index the same dictionary entry. Providing keyword arguments as in the first example only works for keys that are valid Python identifiers. Otherwise, any valid keys can be used. + Dictionaries preserve insertion order. Note that updating a key does not + affect the order. Keys added after deletion are inserted at the end. :: + + >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} + >>> d + {'one': 1, 'two': 2, 'three': 3, 'four': 4} + >>> list(d) + ['one', 'two', 'three', 'four'] + >>> list(d.values()) + [1, 2, 3, 4] + >>> d["one"] = 42 + >>> d + {'one': 42, 'two': 2, 'three': 3, 'four': 4} + >>> del d["two"] + >>> d["two"] = None + >>> d + {'one': 42, 'three': 3, 'four': 4, 'two': None} + + .. versionchanged:: 3.7 + Dictionary order is guaranteed to be insertion order. This behavior was + an implementation detail of CPython from 3.6. These are the operations that dictionaries support (and therefore, custom mapping types should support too): @@ -5008,32 +5035,6 @@ can be used interchangeably to index the same dictionary entry. .. versionadded:: 3.9 - Dictionaries compare equal if and only if they have the same ``(key, - value)`` pairs (regardless of ordering). Order comparisons ('<', '<=', '>=', '>') raise - :exc:`TypeError`. - - Dictionaries preserve insertion order. Note that updating a key does not - affect the order. Keys added after deletion are inserted at the end. :: - - >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} - >>> d - {'one': 1, 'two': 2, 'three': 3, 'four': 4} - >>> list(d) - ['one', 'two', 'three', 'four'] - >>> list(d.values()) - [1, 2, 3, 4] - >>> d["one"] = 42 - >>> d - {'one': 42, 'two': 2, 'three': 3, 'four': 4} - >>> del d["two"] - >>> d["two"] = None - >>> d - {'one': 42, 'three': 3, 'four': 4, 'two': None} - - .. versionchanged:: 3.7 - Dictionary order is guaranteed to be insertion order. This behavior was - an implementation detail of CPython from 3.6. - Dictionaries and dictionary views are reversible. :: >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index a5c4ffa38fe..55e442b20ff 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1292,7 +1292,7 @@ always available. Unless explicitly noted otherwise, all variables are read-only ``sys._jit`` is not guaranteed to exist or behave the same way in all Python implementations, versions, or build configurations. - .. versionadded:: next + .. versionadded:: 3.14 .. function:: _jit.is_available() diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 8e9775ddbc6..f9cb5495e60 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -167,7 +167,7 @@ Some facts and figures: .. versionchanged:: 3.12 The *compresslevel* keyword argument also works for streams. - .. versionchanged:: next + .. versionchanged:: 3.14 The *preset* keyword argument also works for streams. diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index de9ee427bd7..249c0a5cb03 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -561,7 +561,7 @@ since it is impossible to detect the termination of alien threads. of :term:`Python finalization <interpreter shutdown>` :meth:`!join` raises a :exc:`PythonFinalizationError`. - .. versionchanged:: next + .. versionchanged:: 3.14 May raise :exc:`PythonFinalizationError`. diff --git a/Doc/library/token.rst b/Doc/library/token.rst index 1529d173e17..1f92b5df430 100644 --- a/Doc/library/token.rst +++ b/Doc/library/token.rst @@ -140,7 +140,7 @@ The token constants are: The token string includes the prefix and the opening quote(s), but none of the contents of the literal. - .. versionadded:: next + .. versionadded:: 3.14 .. data:: TSTRING_MIDDLE @@ -154,7 +154,7 @@ The token constants are: :data:`LBRACE`, :data:`RBRACE`, :data:`EXCLAMATION` and :data:`COLON` tokens. - .. versionadded:: next + .. versionadded:: 3.14 .. data:: TSTRING_END @@ -164,7 +164,7 @@ The token constants are: The token string contains the closing quote(s). - .. versionadded:: next + .. versionadded:: 3.14 .. data:: ENDMARKER 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 234827132bf..b0f26724d0c 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -171,7 +171,7 @@ The :mod:`urllib.request` module defines the following functions: sections. For example, the path ``/etc/hosts`` is converted to the URL ``///etc/hosts``. - .. versionchanged:: next + .. versionchanged:: 3.14 The *add_scheme* parameter was added. @@ -204,13 +204,13 @@ The :mod:`urllib.request` module defines the following functions: characters not following a drive letter no longer cause an :exc:`OSError` exception to be raised on Windows. - .. versionchanged:: next + .. versionchanged:: 3.14 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 + .. versionchanged:: 3.14 The *require_scheme* and *resolve_host* parameters were added. diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst index cbb2b06c2a0..fd6abc70261 100644 --- a/Doc/library/webbrowser.rst +++ b/Doc/library/webbrowser.rst @@ -29,7 +29,7 @@ already registered browsers this browser is added to the front of the search lis if the part does not contain ``%s``, it is simply interpreted as the name of the browser to launch. [1]_ -.. versionchanged:: next +.. versionchanged:: 3.14 The :envvar:`BROWSER` variable can now also be used to reorder the list of platform defaults. This is particularly useful on macOS where the platform diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index ea5b84b00c0..005a768f684 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -3346,7 +3346,7 @@ left undefined. argument if the three-argument version of the built-in :func:`pow` function is to be supported. - .. versionchanged:: next + .. versionchanged:: 3.14 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 diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst index 02e7de77322..cd526071424 100644 --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -16,7 +16,7 @@ Unix shell's search path makes it possible to start it by typing the command: .. code-block:: text - python3.14 + python3.15 to the shell. [#]_ Since the choice of the directory where the interpreter lives is an installation option, other places are possible; check with your local @@ -97,8 +97,8 @@ before printing the first prompt: .. code-block:: shell-session - $ python3.14 - Python 3.14 (default, April 4 2024, 09:25:04) + $ python3.15 + Python 3.15 (default, May 7 2025, 15:46:04) [GCC 10.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> diff --git a/Doc/tutorial/stdlib.rst b/Doc/tutorial/stdlib.rst index 4b3eef313e7..d83ecca270b 100644 --- a/Doc/tutorial/stdlib.rst +++ b/Doc/tutorial/stdlib.rst @@ -15,7 +15,7 @@ operating system:: >>> import os >>> os.getcwd() # Return the current working directory - 'C:\\Python314' + 'C:\\Python315' >>> os.chdir('/server/accesslogs') # Change current working directory >>> os.system('mkdir today') # Run the command mkdir in the system shell 0 diff --git a/Doc/tutorial/stdlib2.rst b/Doc/tutorial/stdlib2.rst index a2f96b34b2d..678b71c9274 100644 --- a/Doc/tutorial/stdlib2.rst +++ b/Doc/tutorial/stdlib2.rst @@ -279,7 +279,7 @@ applications include caching objects that are expensive to create:: Traceback (most recent call last): File "<stdin>", line 1, in <module> d['primary'] # entry was automatically removed - File "C:/python314/lib/weakref.py", line 46, in __getitem__ + File "C:/python315/lib/weakref.py", line 46, in __getitem__ o = self.data[key]() KeyError: 'primary' diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index c586882b313..40a46a62031 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -73,7 +73,7 @@ source. .. audit-event:: cpython.run_command command cmdoption-c - .. versionchanged:: next + .. versionchanged:: 3.14 *command* is automatically dedented before execution. .. option:: -m <module-name> @@ -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:: 3.14 + + 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,7 +680,7 @@ Miscellaneous options .. versionchanged:: 3.10 Removed the ``-X oldparser`` option. -.. versionremoved:: next +.. versionremoved:: 3.14 :option:`!-J` is no longer reserved for use by Jython_, and now has no special meaning. @@ -982,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:: 3.14 + + Added ``PYTHONPROFILEIMPORTTIME=2`` to also trace imports of loaded modules. + .. envvar:: PYTHONASYNCIODEBUG 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/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index c35e4365de0..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,20 +904,27 @@ 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_, @@ -813,8 +935,8 @@ Other language changes .. _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. @@ -849,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`.) @@ -869,7 +990,7 @@ 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. @@ -894,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`.) @@ -905,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`.) @@ -984,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. @@ -994,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`. @@ -1111,12 +1230,21 @@ 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 @@ -1209,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 @@ -1349,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`.) @@ -1361,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 -------- @@ -1513,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`. @@ -1592,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 @@ -1671,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 @@ -1904,17 +2029,17 @@ Deprecated (Contributed by Inada Naoki in :gh:`133036`.) * :mod:`ctypes`: - 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`.) -* :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* @@ -2080,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`. @@ -2255,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``. @@ -2403,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`.) @@ -2520,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. diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst new file mode 100644 index 00000000000..5e9922069aa --- /dev/null +++ b/Doc/whatsnew/3.15.rst @@ -0,0 +1,157 @@ + +**************************** + What's new in Python 3.15 +**************************** + +:Editor: TBD + +.. Rules for maintenance: + + * Anyone can add text to this document. Do not spend very much time + on the wording of your changes, because your text will probably + get rewritten to some degree. + + * The maintainer will go through Misc/NEWS periodically and add + changes; it's therefore more important to add your changes to + Misc/NEWS than to this file. + + * This is not a complete list of every single change; completeness + is the purpose of Misc/NEWS. Some changes I consider too small + or esoteric to include. If such a change is added to the text, + I'll just remove it. (This is another reason you shouldn't spend + too much time on writing your addition.) + + * If you want to draw your new text to the attention of the + maintainer, add 'XXX' to the beginning of the paragraph or + section. + + * It's OK to just add a fragmentary note about a change. For + example: "XXX Describe the transmogrify() function added to the + socket module." The maintainer will research the change and + write the necessary text. + + * You can comment out your additions if you like, but it's not + necessary (especially when a final release is some months away). + + * Credit the author of a patch or bugfix. Just the name is + sufficient; the e-mail address isn't necessary. + + * It's helpful to add the issue number as a comment: + + XXX Describe the transmogrify() function added to the socket + module. + (Contributed by P.Y. Developer in :gh:`12345`.) + + This saves the maintainer the effort of going through the VCS log + when researching a change. + +This article explains the new features in Python 3.15, compared to 3.14. + +For full details, see the :ref:`changelog <changelog>`. + +.. note:: + + Prerelease users should be aware that this document is currently in draft + form. It will be updated substantially as Python 3.15 moves towards release, + so it's worth checking back even after reading earlier versions. + + +Summary --- release highlights +============================== + +.. This section singles out the most important changes in Python 3.15. + Brevity is key. + + +.. PEP-sized items next. + + + +New features +============ + + + +Other language changes +====================== + + + +New modules +=========== + +* None yet. + + +Improved modules +================ + +module_name +----------- + +* TODO + +.. Add improved modules above alphabetically, not here at the end. + +Optimizations +============= + +module_name +----------- + +* TODO + + + +Deprecated +========== + +* module_name: + TODO + + +.. Add deprecations above alphabetically, not here at the end. + +Removed +======= + +module_name +----------- + +* TODO + + +Porting to Python 3.15 +====================== + +This section lists previously described changes and other bugfixes +that may require changes to your code. + + +Build changes +============= + + +C API changes +============= + +New features +------------ + +* TODO + +Porting to Python 3.15 +---------------------- + +* TODO + +Deprecated C APIs +----------------- + +* TODO + +.. Add C API deprecations above alphabetically, not here at the end. + +Removed C APIs +-------------- + diff --git a/Doc/whatsnew/index.rst b/Doc/whatsnew/index.rst index 6ff722a1894..38194db670b 100644 --- a/Doc/whatsnew/index.rst +++ b/Doc/whatsnew/index.rst @@ -11,6 +11,7 @@ anyone wishing to stay up-to-date after a new release. .. toctree:: :maxdepth: 2 + 3.15.rst 3.14.rst 3.13.rst 3.12.rst |