diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/init.rst | 170 | ||||
| -rw-r--r-- | Doc/c-api/intro.rst | 11 | ||||
| -rw-r--r-- | Doc/c-api/unicode.rst | 11 | ||||
| -rw-r--r-- | Doc/data/refcounts.dat | 13 | ||||
| -rw-r--r-- | Doc/data/stable_abi.dat | 10 | ||||
| -rw-r--r-- | Doc/deprecations/c-api-pending-removal-in-3.15.rst | 12 | ||||
| -rw-r--r-- | Doc/deprecations/pending-removal-in-3.15.rst | 7 | ||||
| -rw-r--r-- | Doc/library/annotationlib.rst | 140 | ||||
| -rw-r--r-- | Doc/library/datetime.rst | 16 | ||||
| -rw-r--r-- | Doc/library/heapq.rst | 1 | ||||
| -rw-r--r-- | Doc/library/math.rst | 3 | ||||
| -rw-r--r-- | Doc/library/shutil.rst | 4 | ||||
| -rw-r--r-- | Doc/library/ssl.rst | 7 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 2 | ||||
| -rw-r--r-- | Doc/library/string.rst | 2 | ||||
| -rw-r--r-- | Doc/library/unittest.mock.rst | 4 | ||||
| -rw-r--r-- | Doc/library/urllib.request.rst | 4 | ||||
| -rw-r--r-- | Doc/reference/compound_stmts.rst | 8 | ||||
| -rw-r--r-- | Doc/using/windows.rst | 2 | ||||
| -rw-r--r-- | Doc/whatsnew/3.10.rst | 6 | ||||
| -rw-r--r-- | Doc/whatsnew/3.13.rst | 12 | ||||
| -rw-r--r-- | Doc/whatsnew/3.14.rst | 79 | ||||
| -rw-r--r-- | Doc/whatsnew/3.15.rst | 88 | ||||
| -rw-r--r-- | Doc/whatsnew/3.8.rst | 4 |
24 files changed, 362 insertions, 254 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 52f64a61006..90767b12471 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -77,10 +77,7 @@ The following functions can be safely called before Python is initialized: Despite their apparent similarity to some of the functions listed above, the following functions **should not be called** before the interpreter has - been initialized: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`, - :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, - :c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`, - :c:func:`Py_GetProgramName`, :c:func:`PyEval_InitThreads`, and + been initialized: :c:func:`Py_EncodeLocale`, :c:func:`PyEval_InitThreads`, and :c:func:`Py_RunMain`. @@ -145,9 +142,6 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2. :c:member:`PyConfig.pathconfig_warnings` should be used instead, see :ref:`Python Initialization Configuration <init-config>`. - Suppress error messages when calculating the module search path in - :c:func:`Py_GetPath`. - Private flag used by ``_freeze_module`` and ``frozenmain`` programs. .. deprecated-removed:: 3.12 3.15 @@ -203,7 +197,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2. Set by the :option:`-i` option. - .. deprecated:: 3.12 + .. deprecated-removed:: 3.12 3.15 .. c:var:: int Py_IsolatedFlag @@ -586,7 +580,6 @@ Process-wide parameters .. index:: single: Py_Initialize() single: main() - single: Py_GetPath() This API is kept for backward compatibility: setting :c:member:`PyConfig.program_name` should be used instead, see :ref:`Python @@ -596,7 +589,7 @@ Process-wide parameters the first time, if it is called at all. It tells the interpreter the value of the ``argv[0]`` argument to the :c:func:`main` function of the program (converted to wide characters). - This is used by :c:func:`Py_GetPath` and some other functions below to find + This is used by some other functions below to find the Python run-time libraries relative to the interpreter executable. The default value is ``'python'``. The argument should point to a zero-terminated wide character string in static storage whose contents will not @@ -609,146 +602,6 @@ Process-wide parameters .. deprecated-removed:: 3.11 3.15 -.. c:function:: wchar_t* Py_GetProgramName() - - Return the program name set with :c:member:`PyConfig.program_name`, or the default. - The returned string points into static storage; the caller should not modify its - value. - - This function should not be called before :c:func:`Py_Initialize`, otherwise - it returns ``NULL``. - - .. versionchanged:: 3.10 - It now returns ``NULL`` if called before :c:func:`Py_Initialize`. - - .. deprecated-removed:: 3.13 3.15 - Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>` - (:data:`sys.executable`) instead. - - -.. c:function:: wchar_t* Py_GetPrefix() - - Return the *prefix* for installed platform-independent files. This is derived - through a number of complicated rules from the program name set with - :c:member:`PyConfig.program_name` and some environment variables; for example, if the - program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The - returned string points into static storage; the caller should not modify its - value. This corresponds to the :makevar:`prefix` variable in the top-level - :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure` - script at build time. The value is available to Python code as ``sys.base_prefix``. - It is only useful on Unix. See also the next function. - - This function should not be called before :c:func:`Py_Initialize`, otherwise - it returns ``NULL``. - - .. versionchanged:: 3.10 - It now returns ``NULL`` if called before :c:func:`Py_Initialize`. - - .. deprecated-removed:: 3.13 3.15 - Use :c:func:`PyConfig_Get("base_prefix") <PyConfig_Get>` - (:data:`sys.base_prefix`) instead. Use :c:func:`PyConfig_Get("prefix") - <PyConfig_Get>` (:data:`sys.prefix`) if :ref:`virtual environments - <venv-def>` need to be handled. - - -.. c:function:: wchar_t* Py_GetExecPrefix() - - Return the *exec-prefix* for installed platform-*dependent* files. This is - derived through a number of complicated rules from the program name set with - :c:member:`PyConfig.program_name` and some environment variables; for example, if the - program name is ``'/usr/local/bin/python'``, the exec-prefix is - ``'/usr/local'``. The returned string points into static storage; the caller - should not modify its value. This corresponds to the :makevar:`exec_prefix` - variable in the top-level :file:`Makefile` and the ``--exec-prefix`` - argument to the :program:`configure` script at build time. The value is - available to Python code as ``sys.base_exec_prefix``. It is only useful on - Unix. - - Background: The exec-prefix differs from the prefix when platform dependent - files (such as executables and shared libraries) are installed in a different - directory tree. In a typical installation, platform dependent files may be - installed in the :file:`/usr/local/plat` subtree while platform independent may - be installed in :file:`/usr/local`. - - Generally speaking, a platform is a combination of hardware and software - families, e.g. Sparc machines running the Solaris 2.x operating system are - considered the same platform, but Intel machines running Solaris 2.x are another - platform, and Intel machines running Linux are yet another platform. Different - major revisions of the same operating system generally also form different - platforms. Non-Unix operating systems are a different story; the installation - strategies on those systems are so different that the prefix and exec-prefix are - meaningless, and set to the empty string. Note that compiled Python bytecode - files are platform independent (but not independent from the Python version by - which they were compiled!). - - System administrators will know how to configure the :program:`mount` or - :program:`automount` programs to share :file:`/usr/local` between platforms - while having :file:`/usr/local/plat` be a different filesystem for each - platform. - - This function should not be called before :c:func:`Py_Initialize`, otherwise - it returns ``NULL``. - - .. versionchanged:: 3.10 - It now returns ``NULL`` if called before :c:func:`Py_Initialize`. - - .. deprecated-removed:: 3.13 3.15 - Use :c:func:`PyConfig_Get("base_exec_prefix") <PyConfig_Get>` - (:data:`sys.base_exec_prefix`) instead. Use - :c:func:`PyConfig_Get("exec_prefix") <PyConfig_Get>` - (:data:`sys.exec_prefix`) if :ref:`virtual environments <venv-def>` need - to be handled. - -.. c:function:: wchar_t* Py_GetProgramFullPath() - - .. index:: - single: executable (in module sys) - - Return the full program name of the Python executable; this is computed as a - side-effect of deriving the default module search path from the program name - (set by :c:member:`PyConfig.program_name`). The returned string points into - static storage; the caller should not modify its value. The value is available - to Python code as ``sys.executable``. - - This function should not be called before :c:func:`Py_Initialize`, otherwise - it returns ``NULL``. - - .. versionchanged:: 3.10 - It now returns ``NULL`` if called before :c:func:`Py_Initialize`. - - .. deprecated-removed:: 3.13 3.15 - Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>` - (:data:`sys.executable`) instead. - - -.. c:function:: wchar_t* Py_GetPath() - - .. index:: - triple: module; search; path - single: path (in module sys) - - Return the default module search path; this is computed from the program name - (set by :c:member:`PyConfig.program_name`) and some environment variables. - The returned string consists of a series of directory names separated by a - platform dependent delimiter character. The delimiter character is ``':'`` - on Unix and macOS, ``';'`` on Windows. The returned string points into - static storage; the caller should not modify its value. The list - :data:`sys.path` is initialized with this value on interpreter startup; it - can be (and usually is) modified later to change the search path for loading - modules. - - This function should not be called before :c:func:`Py_Initialize`, otherwise - it returns ``NULL``. - - .. XXX should give the exact rules - - .. versionchanged:: 3.10 - It now returns ``NULL`` if called before :c:func:`Py_Initialize`. - - .. deprecated-removed:: 3.13 3.15 - Use :c:func:`PyConfig_Get("module_search_paths") <PyConfig_Get>` - (:data:`sys.path`) instead. - .. c:function:: const char* Py_GetVersion() Return the version of this Python interpreter. This is a string that looks @@ -919,23 +772,6 @@ Process-wide parameters .. deprecated-removed:: 3.11 3.15 -.. c:function:: wchar_t* Py_GetPythonHome() - - Return the default "home", that is, the value set by - :c:member:`PyConfig.home`, or the value of the :envvar:`PYTHONHOME` - environment variable if it is set. - - This function should not be called before :c:func:`Py_Initialize`, otherwise - it returns ``NULL``. - - .. versionchanged:: 3.10 - It now returns ``NULL`` if called before :c:func:`Py_Initialize`. - - .. deprecated-removed:: 3.13 3.15 - Use :c:func:`PyConfig_Get("home") <PyConfig_Get>` or the - :envvar:`PYTHONHOME` environment variable instead. - - .. _threads: Thread State and the Global Interpreter Lock diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 2bad0bab224..0c20ad17194 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -779,20 +779,11 @@ found along :envvar:`PATH`.) The user can override this behavior by setting the environment variable :envvar:`PYTHONHOME`, or insert additional directories in front of the standard path by setting :envvar:`PYTHONPATH`. -.. index:: - single: Py_GetPath (C function) - single: Py_GetPrefix (C function) - single: Py_GetExecPrefix (C function) - single: Py_GetProgramFullPath (C function) - The embedding application can steer the search by setting :c:member:`PyConfig.program_name` *before* calling :c:func:`Py_InitializeFromConfig`. Note that :envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is still -inserted in front of the standard path. An application that requires total -control has to provide its own implementation of :c:func:`Py_GetPath`, -:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and -:c:func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`). +inserted in front of the standard path. .. index:: single: Py_IsInitialized (C function) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 95987e872ce..cdd90d05b70 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -645,6 +645,17 @@ APIs: difference being that it decrements the reference count of *right* by one. +.. c:function:: PyObject* PyUnicode_BuildEncodingMap(PyObject* string) + + Return a mapping suitable for decoding a custom single-byte encoding. + Given a Unicode string *string* of up to 256 characters representing an encoding + table, returns either a compact internal mapping object or a dictionary + mapping character ordinals to byte values. Raises a :exc:`TypeError` and + return ``NULL`` on invalid input. + + .. versionadded:: 3.2 + + .. c:function:: const char* PyUnicode_GetDefaultEncoding(void) Return the name of the default string encoding, ``"utf-8"``. diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat index 14990bee6e4..59b31ccf7bc 100644 --- a/Doc/data/refcounts.dat +++ b/Doc/data/refcounts.dat @@ -2778,6 +2778,9 @@ PyUnicode_AppendAndDel:void::: PyUnicode_AppendAndDel:PyObject**:p_left:0: PyUnicode_AppendAndDel:PyObject*:right:-1: +PyUnicode_BuildEncodingMap:PyObject*::+1: +PyUnicode_BuildEncodingMap:PyObject*:string::: + PyUnicode_GetDefaultEncoding:const char*::: PyUnicode_GetDefaultEncoding::void:: @@ -3004,18 +3007,8 @@ Py_GetCompiler:const char*::: Py_GetCopyright:const char*::: -Py_GetExecPrefix:wchar_t*::: - -Py_GetPath:wchar_t*::: - Py_GetPlatform:const char*::: -Py_GetPrefix:wchar_t*::: - -Py_GetProgramFullPath:wchar_t*::: - -Py_GetProgramName:wchar_t*::: - Py_GetVersion:const char*::: Py_INCREF:void::: diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat index a8658d8b80e..e71a40e55e9 100644 --- a/Doc/data/stable_abi.dat +++ b/Doc/data/stable_abi.dat @@ -739,11 +739,7 @@ func,PyUnicode_Append,3.2,, func,PyUnicode_AppendAndDel,3.2,, func,PyUnicode_AsASCIIString,3.2,, func,PyUnicode_AsCharmapString,3.2,, -func,PyUnicode_AsDecodedObject,3.2,, -func,PyUnicode_AsDecodedUnicode,3.2,, -func,PyUnicode_AsEncodedObject,3.2,, func,PyUnicode_AsEncodedString,3.2,, -func,PyUnicode_AsEncodedUnicode,3.2,, func,PyUnicode_AsLatin1String,3.2,, func,PyUnicode_AsMBCSString,3.7,on Windows, func,PyUnicode_AsRawUnicodeEscapeString,3.2,, @@ -861,13 +857,7 @@ func,Py_GetCompiler,3.2,, func,Py_GetConstant,3.13,, func,Py_GetConstantBorrowed,3.13,, func,Py_GetCopyright,3.2,, -func,Py_GetExecPrefix,3.2,, -func,Py_GetPath,3.2,, func,Py_GetPlatform,3.2,, -func,Py_GetPrefix,3.2,, -func,Py_GetProgramFullPath,3.2,, -func,Py_GetProgramName,3.2,, -func,Py_GetPythonHome,3.2,, func,Py_GetRecursionLimit,3.2,, func,Py_GetVersion,3.2,, data,Py_HasFileSystemDefaultEncoding,3.2,, diff --git a/Doc/deprecations/c-api-pending-removal-in-3.15.rst b/Doc/deprecations/c-api-pending-removal-in-3.15.rst index a391566c82c..b87f0a5ecde 100644 --- a/Doc/deprecations/c-api-pending-removal-in-3.15.rst +++ b/Doc/deprecations/c-api-pending-removal-in-3.15.rst @@ -22,27 +22,27 @@ Pending removal in Python 3.15 may return a type other than :class:`bytes`, such as :class:`str`. * Python initialization functions, deprecated in Python 3.13: - * :c:func:`Py_GetPath`: + * :c:func:`!Py_GetPath`: Use :c:func:`PyConfig_Get("module_search_paths") <PyConfig_Get>` (:data:`sys.path`) instead. - * :c:func:`Py_GetPrefix`: + * :c:func:`!Py_GetPrefix`: Use :c:func:`PyConfig_Get("base_prefix") <PyConfig_Get>` (:data:`sys.base_prefix`) instead. Use :c:func:`PyConfig_Get("prefix") <PyConfig_Get>` (:data:`sys.prefix`) if :ref:`virtual environments <venv-def>` need to be handled. - * :c:func:`Py_GetExecPrefix`: + * :c:func:`!Py_GetExecPrefix`: Use :c:func:`PyConfig_Get("base_exec_prefix") <PyConfig_Get>` (:data:`sys.base_exec_prefix`) instead. Use :c:func:`PyConfig_Get("exec_prefix") <PyConfig_Get>` (:data:`sys.exec_prefix`) if :ref:`virtual environments <venv-def>` need to be handled. - * :c:func:`Py_GetProgramFullPath`: + * :c:func:`!Py_GetProgramFullPath`: Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>` (:data:`sys.executable`) instead. - * :c:func:`Py_GetProgramName`: + * :c:func:`!Py_GetProgramName`: Use :c:func:`PyConfig_Get("executable") <PyConfig_Get>` (:data:`sys.executable`) instead. - * :c:func:`Py_GetPythonHome`: + * :c:func:`!Py_GetPythonHome`: Use :c:func:`PyConfig_Get("home") <PyConfig_Get>` or the :envvar:`PYTHONHOME` environment variable instead. diff --git a/Doc/deprecations/pending-removal-in-3.15.rst b/Doc/deprecations/pending-removal-in-3.15.rst index 7b32275ad86..c80588b27b6 100644 --- a/Doc/deprecations/pending-removal-in-3.15.rst +++ b/Doc/deprecations/pending-removal-in-3.15.rst @@ -85,6 +85,13 @@ Pending removal in Python 3.15 has been deprecated since Python 3.13. Use the class-based syntax or the functional syntax instead. + * When using the functional syntax of :class:`~typing.TypedDict`\s, failing + to pass a value to the *fields* parameter (``TD = TypedDict("TD")``) or + passing ``None`` (``TD = TypedDict("TD", None)``) has been deprecated + since Python 3.13. + Use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})`` + to create a TypedDict with zero field. + * The :func:`typing.no_type_check_decorator` decorator function has been deprecated since Python 3.13. After eight years in the :mod:`typing` module, diff --git a/Doc/library/annotationlib.rst b/Doc/library/annotationlib.rst index ff9578b6088..41c9ce479ff 100644 --- a/Doc/library/annotationlib.rst +++ b/Doc/library/annotationlib.rst @@ -127,16 +127,27 @@ Classes Values are the result of evaluating the annotation expressions. - .. attribute:: FORWARDREF + .. attribute:: VALUE_WITH_FAKE_GLOBALS :value: 2 + Special value used to signal that an annotate function is being + evaluated in a special environment with fake globals. When passed this + value, annotate functions should either return the same value as for + the :attr:`Format.VALUE` format, or raise :exc:`NotImplementedError` + to signal that they do not support execution in this environment. + This format is only used internally and should not be passed to + the functions in this module. + + .. attribute:: FORWARDREF + :value: 3 + Values are real annotation values (as per :attr:`Format.VALUE` format) for defined values, and :class:`ForwardRef` proxies for undefined values. Real objects may contain references to :class:`ForwardRef` proxy objects. .. attribute:: STRING - :value: 3 + :value: 4 Values are the text string of the annotation as it appears in the source code, up to modifications including, but not restricted to, @@ -144,17 +155,6 @@ Classes The exact values of these strings may change in future versions of Python. - .. attribute:: VALUE_WITH_FAKE_GLOBALS - :value: 4 - - Special value used to signal that an annotate function is being - evaluated in a special environment with fake globals. When passed this - value, annotate functions should either return the same value as for - the :attr:`Format.VALUE` format, or raise :exc:`NotImplementedError` - to signal that they do not support execution in this environment. - This format is only used internally and should not be passed to - the functions in this module. - .. versionadded:: 3.14 .. class:: ForwardRef @@ -485,3 +485,117 @@ annotations from the class and puts them in a separate attribute: typ.classvars = classvars # Store the ClassVars in a separate attribute return typ + +Limitations of the ``STRING`` format +------------------------------------ + +The :attr:`~Format.STRING` format is meant to approximate the source code +of the annotation, but the implementation strategy used means that it is not +always possible to recover the exact source code. + +First, the stringifier of course cannot recover any information that is not present in +the compiled code, including comments, whitespace, parenthesization, and operations that +get simplified by the compiler. + +Second, the stringifier can intercept almost all operations that involve names looked +up in some scope, but it cannot intercept operations that operate fully on constants. +As a corollary, this also means it is not safe to request the ``STRING`` format on +untrusted code: Python is powerful enough that it is possible to achieve arbitrary +code execution even with no access to any globals or builtins. For example: + +.. code-block:: pycon + + >>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__.__builtins__["print"]("Hello world")): pass + ... + >>> annotationlib.get_annotations(f, format=annotationlib.Format.SOURCE) + Hello world + {'x': 'None'} + +.. note:: + This particular example works as of the time of writing, but it relies on + implementation details and is not guaranteed to work in the future. + +Among the different kinds of expressions that exist in Python, +as represented by the :mod:`ast` module, some expressions are supported, +meaning that the ``STRING`` format can generally recover the original source code; +others are unsupported, meaning that they may result in incorrect output or an error. + +The following are supported (sometimes with caveats): + +* :class:`ast.BinOp` +* :class:`ast.UnaryOp` + + * :class:`ast.Invert` (``~``), :class:`ast.UAdd` (``+``), and :class:`ast.USub` (``-``) are supported + * :class:`ast.Not` (``not``) is not supported + +* :class:`ast.Dict` (except when using ``**`` unpacking) +* :class:`ast.Set` +* :class:`ast.Compare` + + * :class:`ast.Eq` and :class:`ast.NotEq` are supported + * :class:`ast.Lt`, :class:`ast.LtE`, :class:`ast.Gt`, and :class:`ast.GtE` are supported, but the operand may be flipped + * :class:`ast.Is`, :class:`ast.IsNot`, :class:`ast.In`, and :class:`ast.NotIn` are not supported + +* :class:`ast.Call` (except when using ``**`` unpacking) +* :class:`ast.Constant` (though not the exact representation of the constant; for example, escape + sequences in strings are lost; hexadecimal numbers are converted to decimal) +* :class:`ast.Attribute` (assuming the value is not a constant) +* :class:`ast.Subscript` (assuming the value is not a constant) +* :class:`ast.Starred` (``*`` unpacking) +* :class:`ast.Name` +* :class:`ast.List` +* :class:`ast.Tuple` +* :class:`ast.Slice` + +The following are unsupported, but throw an informative error when encountered by the +stringifier: + +* :class:`ast.FormattedValue` (f-strings; error is not detected if conversion specifiers like ``!r`` + are used) +* :class:`ast.JoinedStr` (f-strings) + +The following are unsupported and result in incorrect output: + +* :class:`ast.BoolOp` (``and`` and ``or``) +* :class:`ast.IfExp` +* :class:`ast.Lambda` +* :class:`ast.ListComp` +* :class:`ast.SetComp` +* :class:`ast.DictComp` +* :class:`ast.GeneratorExp` + +The following are disallowed in annotation scopes and therefore not relevant: + +* :class:`ast.NamedExpr` (``:=``) +* :class:`ast.Await` +* :class:`ast.Yield` +* :class:`ast.YieldFrom` + + +Limitations of the ``FORWARDREF`` format +---------------------------------------- + +The :attr:`~Format.FORWARDREF` format aims to produce real values as much +as possible, with anything that cannot be resolved replaced with +:class:`ForwardRef` objects. It is affected by broadly the same Limitations +as the :attr:`~Format.STRING` format: annotations that perform operations on +literals or that use unsupported expression types may raise exceptions when +evaluated using the :attr:`~Format.FORWARDREF` format. + +Below are a few examples of the behavior with unsupported expressions: + +.. code-block:: pycon + + >>> from annotationlib import get_annotations, Format + >>> def zerodiv(x: 1 / 0): ... + >>> get_annotations(zerodiv, format=Format.STRING) + Traceback (most recent call last): + ... + ZeroDivisionError: division by zero + >>> get_annotations(zerodiv, format=Format.FORWARDREF) + Traceback (most recent call last): + ... + ZeroDivisionError: division by zero + >>> def ifexp(x: 1 if y else 0): ... + >>> get_annotations(ifexp, format=Format.STRING) + {'x': '1'} diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 1ce2013f05d..3470f42a6c6 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -261,6 +261,22 @@ A :class:`timedelta` object represents a duration, the difference between two >>> (d.days, d.seconds, d.microseconds) (-1, 86399, 999999) + Since the string representation of :class:`!timedelta` objects can be confusing, + use the following recipe to produce a more readable format: + + .. code-block:: pycon + + >>> def pretty_timedelta(td): + ... if td.days >= 0: + ... return str(td) + ... return f'-({-td!s})' + ... + >>> d = timedelta(hours=-1) + >>> str(d) # not human-friendly + '-1 day, 23:00:00' + >>> pretty_timedelta(d) + '-(1:00:00)' + Class attributes: diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index 183ac9a27d5..462b65bc7af 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -315,6 +315,7 @@ The strange invariant above is meant to be an efficient memory representation for a tournament. The numbers below are *k*, not ``a[k]``: .. figure:: heapq-binary-tree.svg + :class: invert-in-dark-mode :align: center :alt: Example (min-heap) binary tree. diff --git a/Doc/library/math.rst b/Doc/library/math.rst index 0749367045d..394a462b946 100644 --- a/Doc/library/math.rst +++ b/Doc/library/math.rst @@ -144,8 +144,7 @@ Number-theoretic functions .. function:: factorial(n) - Return *n* factorial as an integer. Raises :exc:`ValueError` if *n* is not integral or - is negative. + Return factorial of the nonnegative integer *n*. .. versionchanged:: 3.10 Floats with integral values (like ``5.0``) are no longer accepted. diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 2cbf95bcf53..c78dfe1aafa 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -454,6 +454,10 @@ Directory and files operations :envvar:`PATH` environment variable is read from :data:`os.environ`, falling back to :data:`os.defpath` if it is not set. + If *cmd* contains a directory component, :func:`!which` only checks the + specified path directly and does not search the directories listed in + *path* or in the system's :envvar:`PATH` environment variable. + On Windows, the current directory is prepended to the *path* if *mode* does not include ``os.X_OK``. When the *mode* does include ``os.X_OK``, the Windows API ``NeedCurrentDirectoryForExePathW`` will be consulted to diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index c0dcecf737e..ae2e324d0ab 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -934,6 +934,13 @@ Constants .. versionadded:: 3.13 +.. data:: HAS_PSK_TLS13 + + Whether the OpenSSL library has built-in support for External PSKs in TLS + 1.3 as described in :rfc:`9258`. + + .. versionadded:: next + .. data:: HAS_PHA Whether the OpenSSL library has built-in support for TLS-PHA. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 61d39a6671c..1d9a655c766 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2012,7 +2012,7 @@ expression support in the :mod:`re` module). .. method:: str.isprintable() - Return true if all characters in the string are printable, false if it + Return ``True`` if all characters in the string are printable, ``False`` if it contains at least one non-printable character. Here "printable" means the character is suitable for :func:`repr` to use in diff --git a/Doc/library/string.rst b/Doc/library/string.rst index b44d98819b6..c4012483a52 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -858,7 +858,7 @@ these rules. The methods of :class:`Template` are: .. method:: is_valid() - Returns false if the template has invalid placeholders that will cause + Returns ``False`` if the template has invalid placeholders that will cause :meth:`substitute` to raise :exc:`ValueError`. .. versionadded:: 3.11 diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index 27c169dde72..091562cc9ae 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -2654,9 +2654,9 @@ with any methods on the mock: .. code-block:: pycon - >>> mock.has_data() + >>> mock.header_items() <mock.Mock object at 0x...> - >>> mock.has_data.assret_called_with() # Intentional typo! + >>> mock.header_items.assret_called_with() # Intentional typo! Auto-speccing solves this problem. You can either pass ``autospec=True`` to :func:`patch` / :func:`patch.object` or use the :func:`create_autospec` function to create a diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index b0f26724d0c..58bd111b5cc 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -1121,7 +1121,7 @@ HTTPHandler Objects .. method:: HTTPHandler.http_open(req) Send an HTTP request, which can be either GET or POST, depending on - ``req.has_data()``. + ``req.data``. .. _https-handler-objects: @@ -1133,7 +1133,7 @@ HTTPSHandler Objects .. method:: HTTPSHandler.https_open(req) Send an HTTPS request, which can be either GET or POST, depending on - ``req.has_data()``. + ``req.data``. .. _file-handler-objects: diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index f36ed3e122f..5d4298f70e0 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -1885,7 +1885,7 @@ expressions. The presence of annotations does not change the runtime semantics o the code, except if some mechanism is used that introspects and uses the annotations (such as :mod:`dataclasses` or :func:`functools.singledispatch`). -By default, annotations are lazily evaluated in a :ref:`annotation scope <annotation-scopes>`. +By default, annotations are lazily evaluated in an :ref:`annotation scope <annotation-scopes>`. This means that they are not evaluated when the code containing the annotation is evaluated. Instead, the interpreter saves information that can be used to evaluate the annotation later if requested. The :mod:`annotationlib` module provides tools for evaluating annotations. @@ -1898,6 +1898,12 @@ all annotations are instead stored as strings:: >>> f.__annotations__ {'param': 'annotation'} +This future statement will be deprecated and removed in a future version of Python, +but not before Python 3.13 reaches its end of life (see :pep:`749`). +When it is used, introspection tools like +:func:`annotationlib.get_annotations` and :func:`typing.get_type_hints` are +less likely to be able to resolve annotations at runtime. + .. rubric:: Footnotes diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index c084392ca66..411a4092a8c 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -91,7 +91,7 @@ When you first install a runtime, you will likely be prompted to add a directory to your :envvar:`PATH`. This is optional, if you prefer to use the ``py`` command, but is offered for those who prefer the full range of aliases (such as ``python3.14.exe``) to be available. The directory will be -:file:`%LocalAppData%\Python\bin` by default, but may be customized by an +:file:`%LocalAppData%\\Python\\bin` by default, but may be customized by an administrator. Click Start and search for "Edit environment variables for your account" for the system settings page to add the path. diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst index 3c815721a92..f5e38950756 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -2176,9 +2176,9 @@ Porting to Python 3.10 ``unicodedata.ucnhash_CAPI`` has been moved to the internal C API. (Contributed by Victor Stinner in :issue:`42157`.) -* :c:func:`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, - :c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome` and - :c:func:`Py_GetProgramName` functions now return ``NULL`` if called before +* :c:func:`!Py_GetPath`, :c:func:`!Py_GetPrefix`, :c:func:`!Py_GetExecPrefix`, + :c:func:`!Py_GetProgramFullPath`, :c:func:`!Py_GetPythonHome` and + :c:func:`!Py_GetProgramName` functions now return ``NULL`` if called before :c:func:`Py_Initialize` (before Python is initialized). Use the new :ref:`init-config` API to get the :ref:`init-path-config`. (Contributed by Victor Stinner in :issue:`42260`.) diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst index ff33224e272..b3530f75b2f 100644 --- a/Doc/whatsnew/3.13.rst +++ b/Doc/whatsnew/3.13.rst @@ -2477,17 +2477,17 @@ Deprecated C APIs * :c:func:`PySys_ResetWarnOptions`: Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead. - * :c:func:`Py_GetExecPrefix`: + * :c:func:`!Py_GetExecPrefix`: Get :data:`sys.exec_prefix` instead. - * :c:func:`Py_GetPath`: + * :c:func:`!Py_GetPath`: Get :data:`sys.path` instead. - * :c:func:`Py_GetPrefix`: + * :c:func:`!Py_GetPrefix`: Get :data:`sys.prefix` instead. - * :c:func:`Py_GetProgramFullPath`: + * :c:func:`!Py_GetProgramFullPath`: Get :data:`sys.executable` instead. - * :c:func:`Py_GetProgramName`: + * :c:func:`!Py_GetProgramName`: Get :data:`sys.executable` instead. - * :c:func:`Py_GetPythonHome`: + * :c:func:`!Py_GetPythonHome`: Get :c:member:`PyConfig.home` or the :envvar:`PYTHONHOME` environment variable instead. diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 894f011ec86..11361289874 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -82,12 +82,13 @@ and improvements in user-friendliness and correctness. .. PEP-sized items next. -* :ref:`PEP 649: deferred evaluation of annotations <whatsnew314-pep649>` +* :ref:`PEP 649 and 749: deferred evaluation of annotations <whatsnew314-pep649>` * :ref:`PEP 741: Python Configuration C API <whatsnew314-pep741>` * :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:`Free-threaded mode improvements <whatsnew314-free-threaded-cpython>` * :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>` @@ -153,10 +154,10 @@ As another example, generating HTML attributes from data: .. code-block:: python attributes = {"src": "shrubbery.jpg", "alt": "looks nice"} - template = t"<img {attributes} />" - assert html(template) == '<img src="shrubbery.jpg" alt="looks nice" class="looks-nice" />' + template = t"<img {attributes}>" + assert html(template) == '<img src="shrubbery.jpg" alt="looks nice" class="looks-nice">' -Unlike f-strings, the ``html`` function has access to template attributes +Compared to using an f-string, the ``html`` function has access to template attributes containing the original information: static strings, interpolations, and values from the original scope. Unlike existing templating approaches, t-strings build from the well-known f-string syntax and rules. Template systems thus benefit @@ -361,18 +362,19 @@ Check :pep:`758` for more details. .. _whatsnew314-pep649: -PEP 649: deferred evaluation of annotations -------------------------------------------- +PEP 649 and 749: deferred evaluation of annotations +--------------------------------------------------- The :term:`annotations <annotation>` on functions, classes, and modules are no longer evaluated eagerly. Instead, annotations are stored in special-purpose :term:`annotate functions <annotate function>` and evaluated only when -necessary. This is specified in :pep:`649` and :pep:`749`. +necessary (except if ``from __future__ import annotations`` is used). +This is specified in :pep:`649` and :pep:`749`. This change is designed to make annotations in Python more performant and more usable in most circumstances. The runtime cost for defining annotations is minimized, but it remains possible to introspect annotations at runtime. -It is usually no longer necessary to enclose annotations in strings if they +It is no longer necessary to enclose annotations in strings if they contain forward references. The new :mod:`annotationlib` module provides tools for inspecting deferred @@ -408,7 +410,8 @@ writing annotations the same way you did with previous versions of Python. You will likely be able to remove quoted strings in annotations, which are frequently used for forward references. Similarly, if you use ``from __future__ import annotations`` to avoid having to write strings in annotations, you may well be able to -remove that import. However, if you rely on third-party libraries that read annotations, +remove that import once you support only Python 3.14 and newer. +However, if you rely on third-party libraries that read annotations, those libraries may need changes to support unquoted annotations before they work as expected. @@ -421,6 +424,11 @@ annotations. For example, you may want to use :func:`annotationlib.get_annotatio with the :attr:`~annotationlib.Format.FORWARDREF` format, as the :mod:`dataclasses` module now does. +The external :pypi:`typing_extensions` package provides partial backports of some of the +functionality of the :mod:`annotationlib` module, such as the :class:`~annotationlib.Format` +enum and the :func:`~annotationlib.get_annotations` function. These can be used to +write cross-version code that takes advantage of the new behavior in Python 3.14. + Related changes ^^^^^^^^^^^^^^^ @@ -432,6 +440,10 @@ functions in the standard library, there are many ways in which your code may not work in Python 3.14. To safeguard your code against future changes, use only the documented functionality of the :mod:`annotationlib` module. +In particular, do not read annotations directly from the namespace dictionary +attribute of type objects. Use :func:`annotationlib.get_annotate_from_class_namespace` +during class construction and :func:`annotationlib.get_annotations` afterwards. + ``from __future__ import annotations`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -443,6 +455,11 @@ Python without deferred evaluation of annotations, reaches its end of life in 20 In Python 3.14, the behavior of code using ``from __future__ import annotations`` is unchanged. +(Contributed by Jelle Zijlstra in :gh:`119180`; :pep:`649` was written by Larry Hastings.) + +.. seealso:: + :pep:`649` and :pep:`749`. + Improved error messages ----------------------- @@ -584,8 +601,27 @@ Improved error messages ^^^^^^ SyntaxError: cannot use subscript as import target -.. seealso:: - :pep:`649`. +* Improved error message when trying to add an instance of an unhashable type to + a :class:`dict` or :class:`set`. (Contributed by CF Bolz-Tereick and Victor Stinner + in :gh:`132828`.) + + .. code-block:: pycon + + >>> s = set() + >>> s.add({'pages': 12, 'grade': 'A'}) + Traceback (most recent call last): + File "<python-input-1>", line 1, in <module> + s.add({'pages': 12, 'grade': 'A'}) + ~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + TypeError: cannot use 'dict' as a set element (unhashable type: 'dict') + >>> d = {} + >>> l = [1, 2, 3] + >>> d[l] = 12 + Traceback (most recent call last): + File "<python-input-4>", line 1, in <module> + d[l] = 12 + ~^^^ + TypeError: cannot use 'list' as a dict key (unhashable type: 'list') .. _whatsnew314-pep741: @@ -772,6 +808,27 @@ For further information on how to build Python, see (Contributed by Ken Jin in :gh:`128563`, with ideas on how to implement this in CPython by Mark Shannon, Garrett Gu, Haoran Xu, and Josh Haberman.) +.. _whatsnew314-free-threaded-cpython: + +Free-threaded mode +------------------ + +Free-threaded mode (:pep:`703`), initially added in 3.13, has been significantly improved. +The implementation described in PEP 703 was finished, including C API changes, +and temporary workarounds in the interpreter were replaced with more permanent solutions. +The specializing adaptive interpreter (:pep:`659`) is now enabled in free-threaded mode, +which along with many other optimizations greatly improves its performance. +The performance penalty on single-threaded code in free-threaded mode is now roughly 5-10%, +depending on platform and C compiler used. + +This work was done by many contributors: Sam Gross, Matt Page, Neil Schemenauer, +Thomas Wouters, Donghee Na, Kirill Podoprigora, Ken Jin, Itamar Oren, +Brett Simmers, Dino Viehland, Nathan Goldbaum, Ralf Gommers, Lysandros Nikolaou, +Kumar Aditya, Edgar Margffoy, and many others. + +Some of these contributors are employed by Meta, which has continued to provide +significant engineering resources to support this project. + .. _whatsnew314-pyrepl-highlighting: diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst index 7131eeb697e..8cf5238e6cc 100644 --- a/Doc/whatsnew/3.15.rst +++ b/Doc/whatsnew/3.15.rst @@ -75,6 +75,9 @@ New features Other language changes ====================== +* Several error messages incorrectly using the term "argument" have been corrected. + (Contributed by Stan Ulbrych in :gh:`133382`.) + New modules @@ -86,10 +89,13 @@ New modules Improved modules ================ -module_name ------------ +ssl +--- + +* Indicate through :data:`ssl.HAS_PSK_TLS13` whether the :mod:`ssl` module + supports "External PSKs" in TLSv1.3, as described in RFC 9258. + (Contributed by Will Childs-Klein in :gh:`133624`.) -* TODO .. Add improved modules above alphabetically, not here at the end. @@ -115,10 +121,27 @@ Deprecated Removed ======= -module_name ------------ +sysconfig +--------- -* TODO +* Removed the *check_home* parameter of :func:`sysconfig.is_python_build`. + (Contributed by Filipe Laíns in :gh:`92897`.) + + +typing +------ + +* The undocumented keyword argument syntax for creating + :class:`~typing.NamedTuple` classes (for example, + ``Point = NamedTuple("Point", x=int, y=int)``) is no longer supported. + Use the class-based syntax or the functional syntax instead. + (Contributed by Bénédikt Tran in :gh:`133817`.) + +* Using ``TD = TypedDict("TD")`` or ``TD = TypedDict("TD", None)`` to + construct a :class:`~typing.TypedDict` type with zero field is no + longer supported. Use ``class TD(TypedDict): pass`` + or ``TD = TypedDict("TD", {})`` instead. + (Contributed by Bénédikt Tran in :gh:`133823`.) Porting to Python 3.15 @@ -164,5 +187,58 @@ Deprecated C APIs Removed C APIs -------------- +* Remove deprecated ``PyUnicode`` functions: + + * :c:func:`!PyUnicode_AsDecodedObject`: + Use :c:func:`PyCodec_Decode` instead. + * :c:func:`!PyUnicode_AsDecodedUnicode`: + Use :c:func:`PyCodec_Decode` instead; Note that some codecs (for example, "base64") + may return a type other than :class:`str`, such as :class:`bytes`. + * :c:func:`!PyUnicode_AsEncodedObject`: + Use :c:func:`PyCodec_Encode` instead. + * :c:func:`!PyUnicode_AsEncodedUnicode`: + Use :c:func:`PyCodec_Encode` instead; Note that some codecs (for example, "base64") + may return a type other than :class:`bytes`, such as :class:`str`. + + (Contributed by Stan Ulbrych in :gh:`133612`) + * :c:func:`!PyImport_ImportModuleNoBlock`: deprecated alias of :c:func:`PyImport_ImportModule`. + (Contributed by Bénédikt Tran in :gh:`133644`.) + +The following functions are removed in favor of :c:func:`PyConfig_Get`. +The |pythoncapi_compat_project| can be used to get :c:func:`!PyConfig_Get` +on Python 3.13 and older. + +* Python initialization functions: + + * :c:func:`!Py_GetExecPrefix`: + use :c:func:`PyConfig_Get("base_exec_prefix") <PyConfig_Get>` + (:data:`sys.base_exec_prefix`) instead. + Use :c:func:`PyConfig_Get("exec_prefix") <PyConfig_Get>` + (:data:`sys.exec_prefix`) if :ref:`virtual environments <venv-def>` + need to be handled. + * :c:func:`!Py_GetPath`: + use :c:func:`PyConfig_Get("module_search_paths") <PyConfig_Get>` + (:data:`sys.path`) instead. + * :c:func:`!Py_GetPrefix`: + use :c:func:`PyConfig_Get("base_prefix") <PyConfig_Get>` + (:data:`sys.base_prefix`) instead. + Use :c:func:`PyConfig_Get("prefix") <PyConfig_Get>` + (:data:`sys.prefix`) if :ref:`virtual environments <venv-def>` + need to be handled. + * :c:func:`!Py_GetProgramFullPath`: + use :c:func:`PyConfig_Get("executable") <PyConfig_Get>` + (:data:`sys.executable`) instead. + * :c:func:`!Py_GetProgramName`: + use :c:func:`PyConfig_Get("executable") <PyConfig_Get>` + (:data:`sys.executable`) instead. + * :c:func:`!Py_GetPythonHome`: + use :c:func:`PyConfig_Get("home") <PyConfig_Get>` or the + :envvar:`PYTHONHOME` environment variable instead. + + (Contributed by Bénédikt Tran in :gh:`133644`.) + +.. |pythoncapi_compat_project| replace:: |pythoncapi_compat_project_link|_ +.. |pythoncapi_compat_project_link| replace:: pythoncapi-compat project +.. _pythoncapi_compat_project_link: https://github.com/python/pythoncapi-compat diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst index 7aca35b2959..bc2eb1d0e26 100644 --- a/Doc/whatsnew/3.8.rst +++ b/Doc/whatsnew/3.8.rst @@ -1629,8 +1629,8 @@ Build and C API Changes (Contributed by Pablo Galindo in :issue:`37221`.) * :c:func:`!Py_SetPath` now sets :data:`sys.executable` to the program full - path (:c:func:`Py_GetProgramFullPath`) rather than to the program name - (:c:func:`Py_GetProgramName`). + path (:c:func:`!Py_GetProgramFullPath`) rather than to the program name + (:c:func:`!Py_GetProgramName`). (Contributed by Victor Stinner in :issue:`38234`.) |