mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 08:59:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

Merge branch 'main' into realpath-all-but-last

Browse source
This commit is contained in:
Serhiy Storchaka 2025-07-02 12:17:49 +03:00 • committed by GitHub
commit 436e458abd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
507 changed files with 18253 additions and 9664 deletions
Download patch file Download diff file Expand all files Collapse all files

33
.github/CODEOWNERS vendored
View file

@ -35,6 +35,7 @@ Objects/type* @markshannon
Objects/codeobject.c @markshannon
Objects/frameobject.c @markshannon
Objects/call.c @markshannon
Objects/object.c @ZeroIntensity
Python/ceval*.c @markshannon
Python/ceval*.h @markshannon
Python/codegen.c @markshannon @iritkatriel
@ -44,8 +45,9 @@ Python/flowgraph.c @markshannon @iritkatriel
Python/instruction_sequence.c @iritkatriel
Python/bytecodes.c @markshannon
Python/optimizer*.c @markshannon
Python/optimizer_analysis.c @Fidget-Spinner
Python/optimizer_bytecodes.c @Fidget-Spinner
Python/optimizer_analysis.c @Fidget-Spinner @tomasr8
Python/optimizer_bytecodes.c @Fidget-Spinner @tomasr8
Python/optimizer_symbols.c @tomasr8
Python/symtable.c @JelleZijlstra @carljm
Lib/_pyrepl/* @pablogsal @lysnikolaou @ambv
Lib/test/test_patma.py @brandtbucher
@ -66,8 +68,8 @@ Doc/_static/** @AA-Turner @hugovk
Doc/tools/** @AA-Turner @hugovk
# runtime state/lifecycle
**/*pylifecycle* @ericsnowcurrently
**/*pystate* @ericsnowcurrently
**/*pylifecycle* @ericsnowcurrently @ZeroIntensity
**/*pystate* @ericsnowcurrently @ZeroIntensity
**/*preconfig* @ericsnowcurrently
**/*initconfig* @ericsnowcurrently
**/*pathconfig* @ericsnowcurrently
@ -187,13 +189,13 @@ Include/internal/pycore_time.h @pganssle @abalkin
/Tools/cases_generator/ @markshannon
# AST
Python/ast.c @isidentical @JelleZijlstra @eclips4
Python/ast_preprocess.c @isidentical @eclips4
Parser/asdl.py @isidentical @JelleZijlstra @eclips4
Parser/asdl_c.py @isidentical @JelleZijlstra @eclips4
Lib/ast.py @isidentical @JelleZijlstra @eclips4
Lib/_ast_unparse.py @isidentical @JelleZijlstra @eclips4
Lib/test/test_ast/ @eclips4
Python/ast.c @isidentical @JelleZijlstra @eclips4 @tomasr8
Python/ast_preprocess.c @isidentical @eclips4 @tomasr8
Parser/asdl.py @isidentical @JelleZijlstra @eclips4 @tomasr8
Parser/asdl_c.py @isidentical @JelleZijlstra @eclips4 @tomasr8
Lib/ast.py @isidentical @JelleZijlstra @eclips4 @tomasr8
Lib/_ast_unparse.py @isidentical @JelleZijlstra @eclips4 @tomasr8
Lib/test/test_ast/ @eclips4 @tomasr8
# Mock
/Lib/unittest/mock.py @cjw296
@ -281,9 +283,13 @@ Doc/howto/clinic.rst @erlend-aasland
# Subinterpreters
**/*interpreteridobject.* @ericsnowcurrently
**/*crossinterp* @ericsnowcurrently
Lib/test/support/interpreters/ @ericsnowcurrently
Modules/_interp*module.c @ericsnowcurrently
Lib/test/test__interp*.py @ericsnowcurrently
Lib/concurrent/interpreters/ @ericsnowcurrently
Lib/test/support/channels.py @ericsnowcurrently
Doc/library/concurrent.interpreters.rst @ericsnowcurrently
Lib/test/test_interpreters/ @ericsnowcurrently
Lib/concurrent/futures/interpreter.py @ericsnowcurrently
# Android
**/*Android* @mhsmith @freakboy3742
@ -336,3 +342,6 @@ Modules/_xxtestfuzz/ @ammaraskar
Python/remote_debug.h @pablogsal
Python/remote_debugging.c @pablogsal
Modules/_remote_debugging_module.c @pablogsal @ambv @1st1
# gettext
**/*gettext* @tomasr8

8
.github/workflows/build.yml vendored
View file

@ -527,6 +527,14 @@ jobs:
config_hash: ${{ needs.build-context.outputs.config-hash }}
free-threading: ${{ matrix.free-threading }}
build-ubsan:
name: Undefined behavior sanitizer
needs: build-context
if: needs.build-context.outputs.run-tests == 'true'
uses: ./.github/workflows/reusable-ubsan.yml
with:
config_hash: ${{ needs.build-context.outputs.config-hash }}
cross-build-linux:
name: Cross build Linux
runs-on: ubuntu-latest

4
.github/workflows/jit.yml vendored
View file

@ -5,6 +5,8 @@ on:
- '**jit**'
- 'Python/bytecodes.c'
- 'Python/optimizer*.c'
- 'Python/executor_cases.c.h'
- 'Python/optimizer_cases.c.h'
- '!Python/perf_jit_trampoline.c'
- '!**/*.md'
- '!**/*.ini'
@ -13,6 +15,8 @@ on:
- '**jit**'
- 'Python/bytecodes.c'
- 'Python/optimizer*.c'
- 'Python/executor_cases.c.h'
- 'Python/optimizer_cases.c.h'
- '!Python/perf_jit_trampoline.c'
- '!**/*.md'
- '!**/*.ini'

7
.github/workflows/posix-deps-apt.sh vendored
View file

@ -25,3 +25,10 @@ apt-get -yq install \
uuid-dev \
xvfb \
zlib1g-dev
# Workaround missing libmpdec-dev on ubuntu 24.04:
# https://launchpad.net/~ondrej/+archive/ubuntu/php
# https://deb.sury.org/
sudo add-apt-repository ppa:ondrej/php
apt-get update
apt-get -yq install libmpdec-dev

74
.github/workflows/reusable-ubsan.yml vendored Normal file
View file

@ -0,0 +1,74 @@
name: Reusable Undefined Behavior Sanitizer
on:
workflow_call:
inputs:
config_hash:
required: true
type: string
env:
FORCE_COLOR: 1
jobs:
build-ubsan-reusable:
name: 'Undefined behavior sanitizer'
runs-on: ubuntu-24.04
timeout-minutes: 60
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- name: Runner image version
run: echo "IMAGE_OS_VERSION=${ImageOS}-${ImageVersion}" >> "$GITHUB_ENV"
- name: Restore config.cache
uses: actions/cache@v4
with:
path: config.cache
key: ${{ github.job }}-${{ env.IMAGE_OS_VERSION }}-${{ inputs.config_hash }}
- name: Install dependencies
run: |
sudo ./.github/workflows/posix-deps-apt.sh
# Install clang-20
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 20
- name: UBSAN option setup
run: |
echo "UBSAN_OPTIONS=halt_on_error=1:abort_on_error=1:print_summary=1:print_stacktrace=1" >> "$GITHUB_ENV"
echo "CC=clang" >> "$GITHUB_ENV"
echo "CXX=clang++" >> "$GITHUB_ENV"
- name: Add ccache to PATH
run: |
echo "PATH=/usr/lib/ccache:$PATH" >> "$GITHUB_ENV"
- name: Configure ccache action
uses: hendrikmuhs/ccache-action@v1.2
with:
save: ${{ github.event_name == 'push' }}
max-size: "200M"
- name: Configure CPython
run: >-
./configure
--config-cache
--with-undefined-behavior-sanitizer
--with-pydebug
- name: Set up UBSAN log after configuration
run: |
echo "UBSAN_OPTIONS=${UBSAN_OPTIONS}:log_path=${GITHUB_WORKSPACE}/ubsan_log" >> "$GITHUB_ENV"
- name: Build CPython
run: make -j4
- name: Display build info
run: make pythoninfo
- name: Tests
run: ./python -m test -j4
- name: Display UBSAN logs
if: always()
run: find "${GITHUB_WORKSPACE}" -name 'ubsan_log.*' | xargs head -n 1000
- name: Archive UBSAN logs
if: always()
uses: actions/upload-artifact@v4
with:
name: >-
ubsan-logs
path: ubsan_log.*
if-no-files-found: ignore

1
.gitignore vendored
View file

@ -131,6 +131,7 @@ Tools/unicode/data/
/autom4te.cache
/build/
/builddir/
/compile_commands.json
/config.cache
/config.log
/config.status

7
.pre-commit-config.yaml
View file

@ -34,6 +34,13 @@ repos:
name: Run Black on Tools/jit/
files: ^Tools/jit/
- repo: https://github.com/Lucas-C/pre-commit-hooks
rev: v1.5.5
hooks:
- id: remove-tabs
types: [python]
exclude: ^Tools/c-analyzer/cpython/_parser.py
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
hooks:

6
Doc/c-api/arg.rst
View file

@ -686,6 +686,12 @@ Building values
``p`` (:class:`bool`) [int]
Convert a C :c:expr:`int` to a Python :class:`bool` object.
Be aware that this format requires an ``int`` argument.
Unlike most other contexts in C, variadic arguments are not coerced to
a suitable type automatically.
You can convert another type (for example, a pointer or a float) to a
suitable ``int`` value using ``(x) ? 1 : 0`` or ``!!x``.
.. versionadded:: 3.14
``c`` (:class:`bytes` of length 1) [char]

10
Doc/c-api/capsule.rst
View file

@ -105,9 +105,19 @@ Refer to :ref:`using-capsules` for more information on using these objects.
``module.attribute``. The *name* stored in the capsule must match this
string exactly.
This function splits *name* on the ``.`` character, and imports the first
element. It then processes further elements using attribute lookups.
Return the capsule's internal *pointer* on success. On failure, set an
exception and return ``NULL``.
.. note::
If *name* points to an attribute of some submodule or subpackage, this
submodule or subpackage must be previously imported using other means
(for example, by using :c:func:`PyImport_ImportModule`) for the
attribute lookups to succeed.
.. versionchanged:: 3.3
*no_block* has no effect anymore.

22
Doc/c-api/exceptions.rst
View file

@ -749,6 +749,16 @@ Exception Classes
.. versionadded:: 3.2
.. c:function:: int PyExceptionClass_Check(PyObject *ob)
Return non-zero if *ob* is an exception class, zero otherwise. This function always succeeds.
.. c:function:: const char *PyExceptionClass_Name(PyObject *ob)
Return :c:member:`~PyTypeObject.tp_name` of the exception class *ob*.
Exception Objects
=================
@ -982,6 +992,7 @@ the variables:
.. index::
single: PyExc_BaseException (C var)
single: PyExc_BaseExceptionGroup (C var)
single: PyExc_Exception (C var)
single: PyExc_ArithmeticError (C var)
single: PyExc_AssertionError (C var)
@ -1041,6 +1052,8 @@ the variables:
+=========================================+=================================+==========+
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | [1]_ |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_BaseExceptionGroup` | :exc:`BaseExceptionGroup` | [1]_ |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_Exception` | :exc:`Exception` | [1]_ |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | [1]_ |
@ -1164,6 +1177,9 @@ the variables:
.. versionadded:: 3.6
:c:data:`PyExc_ModuleNotFoundError`.
.. versionadded:: 3.11
:c:data:`PyExc_BaseExceptionGroup`.
These are compatibility aliases to :c:data:`PyExc_OSError`:
.. index::
@ -1207,6 +1223,7 @@ the variables:
single: PyExc_Warning (C var)
single: PyExc_BytesWarning (C var)
single: PyExc_DeprecationWarning (C var)
single: PyExc_EncodingWarning (C var)
single: PyExc_FutureWarning (C var)
single: PyExc_ImportWarning (C var)
single: PyExc_PendingDeprecationWarning (C var)
@ -1225,6 +1242,8 @@ the variables:
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_EncodingWarning` | :exc:`EncodingWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
@ -1245,6 +1264,9 @@ the variables:
.. versionadded:: 3.2
:c:data:`PyExc_ResourceWarning`.
.. versionadded:: 3.10
:c:data:`PyExc_EncodingWarning`.
Notes:
.. [3]

247
Doc/c-api/extension-modules.rst Normal file
View file

@ -0,0 +1,247 @@
.. highlight:: c
.. _extension-modules:
Defining extension modules
--------------------------
A C extension for CPython is a shared library (for example, a ``.so`` file
on Linux, ``.pyd`` DLL on Windows), which is loadable into the Python process
(for example, it is compiled with compatible compiler settings), and which
exports an :ref:`initialization function <extension-export-hook>`.
To be importable by default (that is, by
:py:class:`importlib.machinery.ExtensionFileLoader`),
the shared library must be available on :py:attr:`sys.path`,
and must be named after the module name plus an extension listed in
:py:attr:`importlib.machinery.EXTENSION_SUFFIXES`.
.. note::
Building, packaging and distributing extension modules is best done with
third-party tools, and is out of scope of this document.
One suitable tool is Setuptools, whose documentation can be found at
https://setuptools.pypa.io/en/latest/setuptools.html.
Normally, the initialization function returns a module definition initialized
using :c:func:`PyModuleDef_Init`.
This allows splitting the creation process into several phases:
- Before any substantial code is executed, Python can determine which
capabilities the module supports, and it can adjust the environment or
refuse loading an incompatible extension.
- By default, Python itself creates the module object -- that is, it does
the equivalent of :py:meth:`object.__new__` for classes.
It also sets initial attributes like :attr:`~module.__package__` and
:attr:`~module.__loader__`.
- Afterwards, the module object is initialized using extension-specific
code -- the equivalent of :py:meth:`~object.__init__` on classes.
This is called *multi-phase initialization* to distinguish it from the legacy
(but still supported) *single-phase initialization* scheme,
where the initialization function returns a fully constructed module.
See the :ref:`single-phase-initialization section below <single-phase-initialization>`
for details.
.. versionchanged:: 3.5
Added support for multi-phase initialization (:pep:`489`).
Multiple module instances
.........................
By default, extension modules are not singletons.
For example, if the :py:attr:`sys.modules` entry is removed and the module
is re-imported, a new module object is created, and typically populated with
fresh method and type objects.
The old module is subject to normal garbage collection.
This mirrors the behavior of pure-Python modules.
Additional module instances may be created in
:ref:`sub-interpreters <sub-interpreter-support>`
or after Python runtime reinitialization
(:c:func:`Py_Finalize` and :c:func:`Py_Initialize`).
In these cases, sharing Python objects between module instances would likely
cause crashes or undefined behavior.
To avoid such issues, each instance of an extension module should
be *isolated*: changes to one instance should not implicitly affect the others,
and all state owned by the module, including references to Python objects,
should be specific to a particular module instance.
See :ref:`isolating-extensions-howto` for more details and a practical guide.
A simpler way to avoid these issues is
:ref:`raising an error on repeated initialization <isolating-extensions-optout>`.
All modules are expected to support
:ref:`sub-interpreters <sub-interpreter-support>`, or otherwise explicitly
signal a lack of support.
This is usually achieved by isolation or blocking repeated initialization,
as above.
A module may also be limited to the main interpreter using
the :c:data:`Py_mod_multiple_interpreters` slot.
.. _extension-export-hook:
Initialization function
.......................
The initialization function defined by an extension module has the
following signature:
.. c:function:: PyObject* PyInit_modulename(void)
Its name should be :samp:`PyInit_{<name>}`, with ``<name>`` replaced by the
name of the module.
For modules with ASCII-only names, the function must instead be named
:samp:`PyInit_{<name>}`, with ``<name>`` replaced by the name of the module.
When using :ref:`multi-phase-initialization`, non-ASCII module names
are allowed. In this case, the initialization function name is
:samp:`PyInitU_{<name>}`, with ``<name>`` encoded using Python's
*punycode* encoding with hyphens replaced by underscores. In Python:
.. code-block:: python
def initfunc_name(name):
try:
suffix = b'_' + name.encode('ascii')
except UnicodeEncodeError:
suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
return b'PyInit' + suffix
It is recommended to define the initialization function using a helper macro:
.. c:macro:: PyMODINIT_FUNC
Declare an extension module initialization function.
This macro:
* specifies the :c:expr:`PyObject*` return type,
* adds any special linkage declarations required by the platform, and
* for C++, declares the function as ``extern "C"``.
For example, a module called ``spam`` would be defined like this::
static struct PyModuleDef spam_module = {
.m_base = PyModuleDef_HEAD_INIT,
.m_name = "spam",
...
};
PyMODINIT_FUNC
PyInit_spam(void)
{
return PyModuleDef_Init(&spam_module);
}
It is possible to export multiple modules from a single shared library by
defining multiple initialization functions. However, importing them requires
using symbolic links or a custom importer, because by default only the
function corresponding to the filename is found.
See the `Multiple modules in one library <https://peps.python.org/pep-0489/#multiple-modules-in-one-library>`__
section in :pep:`489` for details.
The initialization function is typically the only non-\ ``static``
item defined in the module's C source.
.. _multi-phase-initialization:
Multi-phase initialization
..........................
Normally, the :ref:`initialization function <extension-export-hook>`
(``PyInit_modulename``) returns a :c:type:`PyModuleDef` instance with
non-``NULL`` :c:member:`~PyModuleDef.m_slots`.
Before it is returned, the ``PyModuleDef`` instance must be initialized
using the following function:
.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
Ensure a module definition is a properly initialized Python object that
correctly reports its type and a reference count.
Return *def* cast to ``PyObject*``, or ``NULL`` if an error occurred.
Calling this function is required for :ref:`multi-phase-initialization`.
It should not be used in other contexts.
Note that Python assumes that ``PyModuleDef`` structures are statically
allocated.
This function may return either a new reference or a borrowed one;
this reference must not be released.
.. versionadded:: 3.5
.. _single-phase-initialization:
Legacy single-phase initialization
..................................
.. attention::
Single-phase initialization is a legacy mechanism to initialize extension
modules, with known drawbacks and design flaws. Extension module authors
are encouraged to use multi-phase initialization instead.
In single-phase initialization, the
:ref:`initialization function <extension-export-hook>` (``PyInit_modulename``)
should create, populate and return a module object.
This is typically done using :c:func:`PyModule_Create` and functions like
:c:func:`PyModule_AddObjectRef`.
Single-phase initialization differs from the :ref:`default <multi-phase-initialization>`
in the following ways:
* Single-phase modules are, or rather *contain*, “singletons”.
When the module is first initialized, Python saves the contents of
the module's ``__dict__`` (that is, typically, the module's functions and
types).
For subsequent imports, Python does not call the initialization function
again.
Instead, it creates a new module object with a new ``__dict__``, and copies
the saved contents to it.
For example, given a single-phase module ``_testsinglephase``
[#testsinglephase]_ that defines a function ``sum`` and an exception class
``error``:
.. code-block:: python
>>> import sys
>>> import _testsinglephase as one
>>> del sys.modules['_testsinglephase']
>>> import _testsinglephase as two
>>> one is two
False
>>> one.__dict__ is two.__dict__
False
>>> one.sum is two.sum
True
>>> one.error is two.error
True
The exact behavior should be considered a CPython implementation detail.
* To work around the fact that ``PyInit_modulename`` does not take a *spec*
argument, some state of the import machinery is saved and applied to the
first suitable module created during the ``PyInit_modulename`` call.
Specifically, when a sub-module is imported, this mechanism prepends the
parent package name to the name of the module.
A single-phase ``PyInit_modulename`` function should create “its” module
object as soon as possible, before any other module objects can be created.
* Non-ASCII module names (``PyInitU_modulename``) are not supported.
* Single-phase modules support module lookup functions like
:c:func:`PyState_FindModule`.
.. [#testsinglephase] ``_testsinglephase`` is an internal module used
in CPython's self-test suite; your installation may or may not
include it.

20
Doc/c-api/function.rst
View file

@ -95,6 +95,13 @@ There are a few functions specific to Python functions.
.. versionadded:: 3.12
.. c:function:: PyObject* PyFunction_GetKwDefaults(PyObject *op)
Return the keyword-only argument default values of the function object *op*. This can be a
dictionary of arguments or ``NULL``.
.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
Return the closure associated with the function object *op*. This can be ``NULL``
@ -123,6 +130,19 @@ There are a few functions specific to Python functions.
Raises :exc:`SystemError` and returns ``-1`` on failure.
.. c:function:: PyObject *PyFunction_GET_CODE(PyObject *op)
PyObject *PyFunction_GET_GLOBALS(PyObject *op)
PyObject *PyFunction_GET_MODULE(PyObject *op)
PyObject *PyFunction_GET_DEFAULTS(PyObject *op)
PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)
PyObject *PyFunction_GET_CLOSURE(PyObject *op)
PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)
These functions are similar to their ``PyFunction_Get*`` counterparts, but
do not do type checking. Passing anything other than an instance of
:c:data:`PyFunction_Type` is undefined behavior.
.. c:function:: int PyFunction_AddWatcher(PyFunction_WatchCallback callback)
Register *callback* as a function watcher for the current interpreter.

1
Doc/c-api/index.rst
View file

@ -17,6 +17,7 @@ document the API functions in detail.
veryhigh.rst
refcounting.rst
exceptions.rst
extension-modules.rst
utilities.rst
abstract.rst
concrete.rst

42
Doc/c-api/init.rst
View file

@ -492,17 +492,8 @@ Initializing and finalizing the interpreter
strings other than those passed in (however, the contents of the strings
pointed to by the argument list are not modified).
The return value will be ``0`` if the interpreter exits normally (i.e.,
without an exception), ``1`` if the interpreter exits due to an exception,
or ``2`` if the argument list does not represent a valid Python command
line.
Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
function will not return ``1``, but exit the process, as long as
``Py_InspectFlag`` is not set. If ``Py_InspectFlag`` is set, execution will
drop into the interactive Python prompt, at which point a second otherwise
unhandled :exc:`SystemExit` will still exit the process, while any other
means of exiting will set the return value as described above.
The return value is ``2`` if the argument list does not represent a valid
Python command line, and otherwise the same as :c:func:`Py_RunMain`.
In terms of the CPython runtime configuration APIs documented in the
:ref:`runtime configuration <init-config>` section (and without accounting
@ -539,23 +530,18 @@ Initializing and finalizing the interpreter
If :c:member:`PyConfig.inspect` is not set (the default), the return value
will be ``0`` if the interpreter exits normally (that is, without raising
an exception), or ``1`` if the interpreter exits due to an exception. If an
otherwise unhandled :exc:`SystemExit` is raised, the function will immediately
exit the process instead of returning ``1``.
an exception), the exit status of an unhandled :exc:`SystemExit`, or ``1``
for any other unhandled exception.
If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option
is used), rather than returning when the interpreter exits, execution will
instead resume in an interactive Python prompt (REPL) using the ``__main__``
module's global namespace. If the interpreter exited with an exception, it
is immediately raised in the REPL session. The function return value is
then determined by the way the *REPL session* terminates: returning ``0``
if the session terminates without raising an unhandled exception, exiting
immediately for an unhandled :exc:`SystemExit`, and returning ``1`` for
any other unhandled exception.
then determined by the way the *REPL session* terminates: ``0``, ``1``, or
the status of a :exc:`SystemExit`, as specified above.
This function always finalizes the Python interpreter regardless of whether
it returns a value or immediately exits the process due to an unhandled
:exc:`SystemExit` exception.
This function always finalizes the Python interpreter before it returns.
See :ref:`Python Configuration <init-python-config>` for an example of a
customized Python that always runs in isolated mode using
@ -1264,7 +1250,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp)
Reset all information in an interpreter state object. There must be
an :term:`attached thread state` for the the interpreter.
an :term:`attached thread state` for the interpreter.
.. audit-event:: cpython.PyInterpreterState_Clear "" c.PyInterpreterState_Clear
@ -2291,6 +2277,18 @@ The C-API provides a basic mutual exclusion lock.
.. versionadded:: 3.13
.. c:function:: int PyMutex_IsLocked(PyMutex *m)
Returns non-zero if the mutex *m* is currently locked, zero otherwise.
.. note::
This function is intended for use in assertions and debugging only and
should not be used to make concurrency control decisions, as the lock
state may change immediately after the check.
.. versionadded:: next
.. _python-critical-section-api:
Python Critical Section API

26
Doc/c-api/intro.rst
View file

@ -111,33 +111,11 @@ Useful macros
=============
Several useful macros are defined in the Python header files. Many are
defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
defined closer to where they are useful (for example, :c:macro:`Py_RETURN_NONE`,
:c:macro:`PyMODINIT_FUNC`).
Others of a more general utility are defined here. This is not necessarily a
complete listing.
.. c:macro:: PyMODINIT_FUNC
Declare an extension module ``PyInit`` initialization function. The function
return type is :c:expr:`PyObject*`. The macro declares any special linkage
declarations required by the platform, and for C++ declares the function as
``extern "C"``.
The initialization function must be named :samp:`PyInit_{name}`, where
*name* is the name of the module, and should be the only non-\ ``static``
item defined in the module file. Example::
static struct PyModuleDef spam_module = {
.m_base = PyModuleDef_HEAD_INIT,
.m_name = "spam",
...
};
PyMODINIT_FUNC
PyInit_spam(void)
{
return PyModuleDef_Init(&spam_module);
}
.. c:macro:: Py_ABS(x)

2
Doc/c-api/long.rst
View file

@ -439,7 +439,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
All *n_bytes* of the buffer are written: large buffers are padded with
zeroes.
If the returned value is greater than than *n_bytes*, the value was
If the returned value is greater than *n_bytes*, the value was
truncated: as many of the lowest bits of the value as could fit are written,
and the higher bits are ignored. This matches the typical behavior
of a C-style downcast.

271
Doc/c-api/module.rst
View file

@ -127,25 +127,36 @@ Module Objects
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
.. _initializing-modules:
.. _pymoduledef:
Initializing C modules
^^^^^^^^^^^^^^^^^^^^^^
Module definitions
------------------
Modules objects are usually created from extension modules (shared libraries
which export an initialization function), or compiled-in modules
(where the initialization function is added using :c:func:`PyImport_AppendInittab`).
See :ref:`building` or :ref:`extending-with-embedding` for details.
The functions in the previous section work on any module object, including
modules imported from Python code.
The initialization function can either pass a module definition instance
to :c:func:`PyModule_Create`, and return the resulting module object,
or request "multi-phase initialization" by returning the definition struct itself.
Modules defined using the C API typically use a *module definition*,
:c:type:`PyModuleDef` -- a statically allocated, constant “description" of
how a module should be created.
The definition is usually used to define an extension's “main” module object
(see :ref:`extension-modules` for details).
It is also used to
:ref:`create extension modules dynamically <moduledef-dynamic>`.
Unlike :c:func:`PyModule_New`, the definition allows management of
*module state* -- a piece of memory that is allocated and cleared together
with the module object.
Unlike the module's Python attributes, Python code cannot replace or delete
data stored in module state.
.. c:type:: PyModuleDef
The module definition struct, which holds all information needed to create
a module object. There is usually only one statically initialized variable
of this type for each module.
a module object.
This structure must be statically allocated (or be otherwise guaranteed
to be valid while any modules created from it exist).
Usually, there is only one variable of this type for each extension module.
.. c:member:: PyModuleDef_Base m_base
@ -170,13 +181,15 @@ or request "multi-phase initialization" by returning the definition struct itsel
and freed when the module object is deallocated, after the
:c:member:`~PyModuleDef.m_free` function has been called, if present.
Setting ``m_size`` to ``-1`` means that the module does not support
sub-interpreters, because it has global state.
Setting it to a non-negative value means that the module can be
re-initialized and specifies the additional amount of memory it requires
for its state. Non-negative ``m_size`` is required for multi-phase
initialization.
for its state.
Setting ``m_size`` to ``-1`` means that the module does not support
sub-interpreters, because it has global state.
Negative ``m_size`` is only allowed when using
:ref:`legacy single-phase initialization <single-phase-initialization>`
or when :ref:`creating modules dynamically <moduledef-dynamic>`.
See :PEP:`3121` for more details.
@ -189,7 +202,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
An array of slot definitions for multi-phase initialization, terminated by
a ``{0, NULL}`` entry.
When using single-phase initialization, *m_slots* must be ``NULL``.
When using legacy single-phase initialization, *m_slots* must be ``NULL``.
.. versionchanged:: 3.5
@ -249,96 +262,9 @@ or request "multi-phase initialization" by returning the definition struct itsel
.. versionchanged:: 3.9
No longer called before the module state is allocated.
Single-phase initialization
...........................
The module initialization function may create and return the module object
directly. This is referred to as "single-phase initialization", and uses one
of the following two module creation functions:
.. c:function:: PyObject* PyModule_Create(PyModuleDef *def)
Create a new module object, given the definition in *def*. This behaves
like :c:func:`PyModule_Create2` with *module_api_version* set to
:c:macro:`PYTHON_API_VERSION`.
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
Create a new module object, given the definition in *def*, assuming the
API version *module_api_version*. If that version does not match the version
of the running interpreter, a :exc:`RuntimeWarning` is emitted.
Return ``NULL`` with an exception set on error.
.. note::
Most uses of this function should be using :c:func:`PyModule_Create`
instead; only use this if you are sure you need it.
Before it is returned from in the initialization function, the resulting module
object is typically populated using functions like :c:func:`PyModule_AddObjectRef`.
.. _multi-phase-initialization:
Multi-phase initialization
..........................
An alternate way to specify extensions is to request "multi-phase initialization".
Extension modules created this way behave more like Python modules: the
initialization is split between the *creation phase*, when the module object
is created, and the *execution phase*, when it is populated.
The distinction is similar to the :py:meth:`~object.__new__` and
:py:meth:`~object.__init__` methods of classes.
Unlike modules created using single-phase initialization, these modules are not
singletons.
For example, if the :py:attr:`sys.modules` entry is removed and the module
is re-imported, a new module object is created, and typically populated with
fresh method and type objects.
The old module is subject to normal garbage collection.
This mirrors the behavior of pure-Python modules.
Additional module instances may be created in
:ref:`sub-interpreters <sub-interpreter-support>`
or after after Python runtime reinitialization
(:c:func:`Py_Finalize` and :c:func:`Py_Initialize`).
In these cases, sharing Python objects between module instances would likely
cause crashes or undefined behavior.
To avoid such issues, each instance of an extension module should
be *isolated*: changes to one instance should not implicitly affect the others,
and all state, including references to Python objects, should be specific to
a particular module instance.
See :ref:`isolating-extensions-howto` for more details and a practical guide.
A simpler way to avoid these issues is
:ref:`raising an error on repeated initialization <isolating-extensions-optout>`.
All modules created using multi-phase initialization are expected to support
:ref:`sub-interpreters <sub-interpreter-support>`, or otherwise explicitly
signal a lack of support.
This is usually achieved by isolation or blocking repeated initialization,
as above.
A module may also be limited to the main interpreter using
the :c:data:`Py_mod_multiple_interpreters` slot.
To request multi-phase initialization, the initialization function
(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty
:c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef``
instance must be initialized with the following function:
.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
Ensures a module definition is a properly initialized Python object that
correctly reports its type and reference count.
Returns *def* cast to ``PyObject*``, or ``NULL`` if an error occurred.
.. versionadded:: 3.5
The *m_slots* member of the module definition must point to an array of
``PyModuleDef_Slot`` structures:
Module slots
............
.. c:type:: PyModuleDef_Slot
@ -352,8 +278,6 @@ The *m_slots* member of the module definition must point to an array of
.. versionadded:: 3.5
The *m_slots* array must be terminated by a slot with id 0.
The available slot types are:
.. c:macro:: Py_mod_create
@ -464,21 +388,48 @@ The available slot types are:
.. versionadded:: 3.13
See :PEP:`489` for more details on multi-phase initialization.
Low-level module creation functions
...................................
.. _moduledef-dynamic:
The following functions are called under the hood when using multi-phase
initialization. They can be used directly, for example when creating module
objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
``PyModule_ExecDef`` must be called to fully initialize a module.
Creating extension modules dynamically
--------------------------------------
The following functions may be used to create a module outside of an
extension's :ref:`initialization function <extension-export-hook>`.
They are also used in
:ref:`single-phase initialization <single-phase-initialization>`.
.. c:function:: PyObject* PyModule_Create(PyModuleDef *def)
Create a new module object, given the definition in *def*.
This is a macro that calls :c:func:`PyModule_Create2` with
*module_api_version* set to :c:macro:`PYTHON_API_VERSION`, or
to :c:macro:`PYTHON_ABI_VERSION` if using the
:ref:`limited API <limited-c-api>`.
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
Create a new module object, given the definition in *def*, assuming the
API version *module_api_version*. If that version does not match the version
of the running interpreter, a :exc:`RuntimeWarning` is emitted.
Return ``NULL`` with an exception set on error.
This function does not support slots.
The :c:member:`~PyModuleDef.m_slots` member of *def* must be ``NULL``.
.. note::
Most uses of this function should be using :c:func:`PyModule_Create`
instead; only use this if you are sure you need it.
.. c:function:: PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
Create a new module object, given the definition in *def* and the
ModuleSpec *spec*. This behaves like :c:func:`PyModule_FromDefAndSpec2`
with *module_api_version* set to :c:macro:`PYTHON_API_VERSION`.
This macro calls :c:func:`PyModule_FromDefAndSpec2` with
*module_api_version* set to :c:macro:`PYTHON_API_VERSION`, or
to :c:macro:`PYTHON_ABI_VERSION` if using the
:ref:`limited API <limited-c-api>`.
.. versionadded:: 3.5
@ -491,6 +442,10 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
Return ``NULL`` with an exception set on error.
Note that this does not process execution slots (:c:data:`Py_mod_exec`).
Both ``PyModule_FromDefAndSpec`` and ``PyModule_ExecDef`` must be called
to fully initialize a module.
.. note::
Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec`
@ -504,35 +459,29 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
.. versionadded:: 3.5
.. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
.. c:macro:: PYTHON_API_VERSION
Set the docstring for *module* to *docstring*.
This function is called automatically when creating a module from
``PyModuleDef``, using either ``PyModule_Create`` or
``PyModule_FromDefAndSpec``.
The C API version. Defined for backwards compatibility.
.. versionadded:: 3.5
Currently, this constant is not updated in new Python versions, and is not
useful for versioning. This may change in the future.
.. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
.. c:macro:: PYTHON_ABI_VERSION
Add the functions from the ``NULL`` terminated *functions* array to *module*.
Refer to the :c:type:`PyMethodDef` documentation for details on individual
entries (due to the lack of a shared module namespace, module level
"functions" implemented in C typically receive the module as their first
parameter, making them similar to instance methods on Python classes).
This function is called automatically when creating a module from
``PyModuleDef``, using either ``PyModule_Create`` or
``PyModule_FromDefAndSpec``.
Defined as ``3`` for backwards compatibility.
Currently, this constant is not updated in new Python versions, and is not
useful for versioning. This may change in the future.
.. versionadded:: 3.5
Support functions
.................
-----------------
The module initialization function (if using single phase initialization) or
a function called from a module execution slot (if using multi-phase
initialization), can use the following functions to help initialize the module
state:
The following functions are provided to help initialize a module
state.
They are intended for a module's execution slots (:c:data:`Py_mod_exec`),
the initialization function for legacy :ref:`single-phase initialization <single-phase-initialization>`,
or code that creates modules dynamically.
.. c:function:: int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)
@ -681,12 +630,39 @@ state:
.. versionadded:: 3.9
.. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
Add the functions from the ``NULL`` terminated *functions* array to *module*.
Refer to the :c:type:`PyMethodDef` documentation for details on individual
entries (due to the lack of a shared module namespace, module level
"functions" implemented in C typically receive the module as their first
parameter, making them similar to instance methods on Python classes).
This function is called automatically when creating a module from
``PyModuleDef`` (such as when using :ref:`multi-phase-initialization`,
``PyModule_Create``, or ``PyModule_FromDefAndSpec``).
Some module authors may prefer defining functions in multiple
:c:type:`PyMethodDef` arrays; in that case they should call this function
directly.
.. versionadded:: 3.5
.. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
Set the docstring for *module* to *docstring*.
This function is called automatically when creating a module from
``PyModuleDef`` (such as when using :ref:`multi-phase-initialization`,
``PyModule_Create``, or ``PyModule_FromDefAndSpec``).
.. versionadded:: 3.5
.. c:function:: int PyUnstable_Module_SetGIL(PyObject *module, void *gil)
Indicate that *module* does or does not support running without the global
interpreter lock (GIL), using one of the values from
:c:macro:`Py_mod_gil`. It must be called during *module*'s initialization
function. If this function is not called during module initialization, the
function when using :ref:`single-phase-initialization`.
If this function is not called during module initialization, the
import machinery assumes the module does not support running without the
GIL. This function is only available in Python builds configured with
:option:`--disable-gil`.
@ -695,10 +671,11 @@ state:
.. versionadded:: 3.13
Module lookup
^^^^^^^^^^^^^
Module lookup (single-phase initialization)
...........................................
Single-phase initialization creates singleton modules that can be looked up
The legacy :ref:`single-phase initialization <single-phase-initialization>`
initialization scheme creates singleton modules that can be looked up
in the context of the current interpreter. This allows the module object to be
retrieved later with only a reference to the module definition.
@ -719,7 +696,8 @@ since multiple such modules can be created from a single definition.
Only effective on modules created using single-phase initialization.
Python calls ``PyState_AddModule`` automatically after importing a module,
Python calls ``PyState_AddModule`` automatically after importing a module
that uses :ref:`single-phase initialization <single-phase-initialization>`,
so it is unnecessary (but harmless) to call it from module initialization
code. An explicit call is needed only if the module's own init code
subsequently calls ``PyState_FindModule``.
@ -727,6 +705,9 @@ since multiple such modules can be created from a single definition.
mechanisms (either by calling it directly, or by referring to its
implementation for details of the required state updates).
If a module was attached previously using the same *def*, it is replaced
by the new *module*.
The caller must have an :term:`attached thread state`.
Return ``-1`` with an exception set on error, ``0`` on success.

2
Doc/c-api/refcounting.rst
View file

@ -210,7 +210,7 @@ of Python objects.
Py_SETREF(dst, src);
That arranges to set *dst* to *src* _before_ releasing the reference
That arranges to set *dst* to *src* *before* releasing the reference
to the old value of *dst*, so that any code triggered as a side-effect
of *dst* getting torn down no longer believes *dst* points
to a valid object.

4
Doc/c-api/type.rst
View file

@ -282,6 +282,10 @@ Type Objects
and other places where a method's defining class cannot be passed using the
:c:type:`PyCMethod` calling convention.
The returned reference is :term:`borrowed <borrowed reference>` from *type*,
and will be valid as long as you hold a reference to *type*.
Do not release it with :c:func:`Py_DECREF` or similar.
.. versionadded:: 3.11
.. c:function:: int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)

20
Doc/c-api/typeobj.rst
View file

@ -686,6 +686,26 @@ and :c:data:`PyType_Type` effectively act as defaults.)
instance, and call the type's :c:member:`~PyTypeObject.tp_free` function to
free the object itself.
If you may call functions that may set the error indicator, you must use
:c:func:`PyErr_GetRaisedException` and :c:func:`PyErr_SetRaisedException`
to ensure you don't clobber a preexisting error indicator (the deallocation
could have occurred while processing a different error):
.. code-block:: c
static void
foo_dealloc(foo_object *self)
{
PyObject *et, *ev, *etb;
PyObject *exc = PyErr_GetRaisedException();
...
PyErr_SetRaisedException(exc);
}
The dealloc handler itself must not raise an exception; if it hits an error
case it should call :c:func:`PyErr_FormatUnraisable` to log (and clear) an
unraisable exception.
No guarantees are made about when an object is destroyed, except:
* Python will destroy an object immediately or some time after the final

18
Doc/c-api/unicode.rst
View file

@ -191,6 +191,22 @@ access to internal read-only data of Unicode objects:
.. versionadded:: 3.2
.. c:function:: Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *str)
If the hash of *str*, as returned by :c:func:`PyObject_Hash`, has been
cached and is immediately available, return it.
Otherwise, return ``-1`` *without* setting an exception.
If *str* is not a string (that is, if ``PyUnicode_Check(obj)``
is false), the behavior is undefined.
This function never fails with an exception.
Note that there are no guarantees on when an object's hash is cached,
and the (non-)existence of a cached hash does not imply that the string has
any other properties.
Unicode Character Properties
""""""""""""""""""""""""""""
@ -1811,7 +1827,7 @@ object.
On success, return ``0``.
On error, set an exception, leave the writer unchanged, and return ``-1``.
.. versionadded:: next
.. versionadded:: 3.14
.. c:function:: int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)

6
Doc/conf.py
View file

@ -79,6 +79,10 @@ version, release = import_module('patchlevel').get_version_info()
rst_epilog = f"""
.. |python_version_literal| replace:: ``Python {version}``
.. |python_x_dot_y_literal| replace:: ``python{version}``
.. |python_x_dot_y_t_literal| replace:: ``python{version}t``
.. |python_x_dot_y_t_literal_config| replace:: ``python{version}t-config``
.. |x_dot_y_b2_literal| replace:: ``{version}.0b2``
.. |applications_python_version_literal| replace:: ``/Applications/Python {version}/``
.. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}``
.. Apparently this how you hack together a formatted link:
@ -234,6 +238,7 @@ nitpick_ignore += [
('c:data', 'PyExc_AssertionError'),
('c:data', 'PyExc_AttributeError'),
('c:data', 'PyExc_BaseException'),
('c:data', 'PyExc_BaseExceptionGroup'),
('c:data', 'PyExc_BlockingIOError'),
('c:data', 'PyExc_BrokenPipeError'),
('c:data', 'PyExc_BufferError'),
@ -287,6 +292,7 @@ nitpick_ignore += [
# C API: Standard Python warning classes
('c:data', 'PyExc_BytesWarning'),
('c:data', 'PyExc_DeprecationWarning'),
('c:data', 'PyExc_EncodingWarning'),
('c:data', 'PyExc_FutureWarning'),
('c:data', 'PyExc_ImportWarning'),
('c:data', 'PyExc_PendingDeprecationWarning'),

31
Doc/data/refcounts.dat
View file

@ -963,21 +963,45 @@ PyFunction_Check:PyObject*:o:0:
PyFunction_GetAnnotations:PyObject*::0:
PyFunction_GetAnnotations:PyObject*:op:0:
PyFunction_GET_ANNOTATIONS:PyObject*::0:
PyFunction_GET_ANNOTATIONS:PyObject*:op:0:
PyFunction_GetClosure:PyObject*::0:
PyFunction_GetClosure:PyObject*:op:0:
PyFunction_GET_CLOSURE:PyObject*::0:
PyFunction_GET_CLOSURE:PyObject*:op:0:
PyFunction_GetCode:PyObject*::0:
PyFunction_GetCode:PyObject*:op:0:
PyFunction_GET_CODE:PyObject*::0:
PyFunction_GET_CODE:PyObject*:op:0:
PyFunction_GetDefaults:PyObject*::0:
PyFunction_GetDefaults:PyObject*:op:0:
PyFunction_GET_DEFAULTS:PyObject*::0:
PyFunction_GET_DEFAULTS:PyObject*:op:0:
PyFunction_GetKwDefaults:PyObject*::0:
PyFunction_GetKwDefaults:PyObject*:op:0:
PyFunction_GET_KW_DEFAULTS:PyObject*::0:
PyFunction_GET_KW_DEFAULTS:PyObject*:op:0:
PyFunction_GetGlobals:PyObject*::0:
PyFunction_GetGlobals:PyObject*:op:0:
PyFunction_GET_GLOBALS:PyObject*::0:
PyFunction_GET_GLOBALS:PyObject*:op:0:
PyFunction_GetModule:PyObject*::0:
PyFunction_GetModule:PyObject*:op:0:
PyFunction_GET_MODULE:PyObject*::0:
PyFunction_GET_MODULE:PyObject*:op:0:
PyFunction_New:PyObject*::+1:
PyFunction_New:PyObject*:code:+1:
PyFunction_New:PyObject*:globals:+1:
@ -1489,9 +1513,6 @@ PyModule_SetDocString:int:::
PyModule_SetDocString:PyObject*:module:0:
PyModule_SetDocString:const char*:docstring::
PyModuleDef_Init:PyObject*::0:
PyModuleDef_Init:PyModuleDef*:def::
PyNumber_Absolute:PyObject*::+1:
PyNumber_Absolute:PyObject*:o:0:
@ -2388,6 +2409,10 @@ PyType_GetFlags:PyTypeObject*:type:0:
PyType_GetName:PyObject*::+1:
PyType_GetName:PyTypeObject*:type:0:
PyType_GetModuleByDef:PyObject*::0:
PyType_GetModuleByDef:PyTypeObject*:type:0:
PyType_GetModuleByDef:PyModuleDef*:def::
PyType_GetQualName:PyObject*::+1:
PyType_GetQualName:PyTypeObject*:type:0:

2
Doc/deprecations/pending-removal-in-3.15.rst
View file

@ -97,6 +97,8 @@ Pending removal in Python 3.15
After eight years in the :mod:`typing` module,
it has yet to be supported by any major type checker.
* :mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules.
* :mod:`wave`:
* The ``getmark()``, ``setmark()`` and ``getmarkers()`` methods of

2
Doc/deprecations/pending-removal-in-future.rst
View file

@ -89,8 +89,6 @@ although there is currently no date scheduled for their removal.
underscore.
(Contributed by Serhiy Storchaka in :gh:`91760`.)
* :mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules.
* :mod:`shutil`: :func:`~shutil.rmtree`'s *onerror* parameter is deprecated in
Python 3.12; use the *onexc* parameter instead.

49
Doc/extending/building.rst
View file

@ -6,41 +6,10 @@
Building C and C++ Extensions
*****************************
A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
``.pyd`` on Windows), which exports an *initialization function*.
A C extension for CPython is a shared library (for example, a ``.so`` file on
Linux, ``.pyd`` on Windows), which exports an *initialization function*.
To be importable, the shared library must be available on :envvar:`PYTHONPATH`,
and must be named after the module name, with an appropriate extension.
When using setuptools, the correct filename is generated automatically.
The initialization function has the signature:
.. c:function:: PyObject* PyInit_modulename(void)
It returns either a fully initialized module, or a :c:type:`PyModuleDef`
instance. See :ref:`initializing-modules` for details.
.. highlight:: python
For modules with ASCII-only names, the function must be named
:samp:`PyInit_{<name>}`, with ``<name>`` replaced by the name of the module.
When using :ref:`multi-phase-initialization`, non-ASCII module names
are allowed. In this case, the initialization function name is
:samp:`PyInitU_{<name>}`, with ``<name>`` encoded using Python's
*punycode* encoding with hyphens replaced by underscores. In Python::
def initfunc_name(name):
try:
suffix = b'_' + name.encode('ascii')
except UnicodeEncodeError:
suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
return b'PyInit' + suffix
It is possible to export multiple modules from a single shared library by
defining multiple initialization functions. However, importing them requires
using symbolic links or a custom importer, because by default only the
function corresponding to the filename is found.
See the *"Multiple modules in one library"* section in :pep:`489` for details.
See :ref:`extension-modules` for details.
.. highlight:: c
@ -51,7 +20,11 @@ See the *"Multiple modules in one library"* section in :pep:`489` for details.
Building C and C++ Extensions with setuptools
=============================================
Python 3.12 and newer no longer come with distutils. Please refer to the
``setuptools`` documentation at
https://setuptools.readthedocs.io/en/latest/setuptools.html
to learn more about how build and distribute C/C++ extensions with setuptools.
Building, packaging and distributing extension modules is best done with
third-party tools, and is out of scope of this document.
One suitable tool is Setuptools, whose documentation can be found at
https://setuptools.pypa.io/en/latest/setuptools.html.
The :mod:`distutils` module, which was included in the standard library
until Python 3.12, is now maintained as part of Setuptools.

2
Doc/extending/newtypes_tutorial.rst
View file

@ -277,7 +277,7 @@ be an instance of a subclass.
The explicit cast to ``CustomObject *`` above is needed because we defined
``Custom_dealloc`` to take a ``PyObject *`` argument, as the ``tp_dealloc``
function pointer expects to receive a ``PyObject *`` argument.
By assigning to the the ``tp_dealloc`` slot of a type, we declare
By assigning to the ``tp_dealloc`` slot of a type, we declare
that it can only be called with instances of our ``CustomObject``
class, so the cast to ``(CustomObject *)`` is safe.
This is object-oriented polymorphism, in C!

4
Doc/howto/free-threading-extensions.rst
View file

@ -6,8 +6,8 @@
C API Extension Support for Free Threading
******************************************
Starting with the 3.13 release, CPython has experimental support for running
with the :term:`global interpreter lock` (GIL) disabled in a configuration
Starting with the 3.13 release, CPython has support for running with
the :term:`global interpreter lock` (GIL) disabled in a configuration
called :term:`free threading`. This document describes how to adapt C API
extensions to support free threading.

17
Doc/howto/free-threading-python.rst
View file

@ -1,18 +1,21 @@
.. _freethreading-python-howto:
**********************************************
Python experimental support for free threading
**********************************************
*********************************
Python support for free threading
*********************************
Starting with the 3.13 release, CPython has experimental support for a build of
Starting with the 3.13 release, CPython has support for a build of
Python called :term:`free threading` where the :term:`global interpreter lock`
(GIL) is disabled. Free-threaded execution allows for full utilization of the
available processing power by running threads in parallel on available CPU cores.
While not all software will benefit from this automatically, programs
designed with threading in mind will run faster on multi-core hardware.
**The free-threaded mode is experimental** and work is ongoing to improve it:
expect some bugs and a substantial single-threaded performance hit.
The free-threaded mode is working and continues to be improved, but
there is some additional overhead in single-threaded workloads compared
to the regular build. Additionally, third-party packages, in particular ones
with an :term:`extension module`, may not be ready for use in a
free-threaded build, and will re-enable the :term:`GIL`.
This document describes the implications of free threading
for Python code. See :ref:`freethreading-extensions-howto` for information on
@ -43,7 +46,7 @@ Identifying free-threaded Python
================================
To check if the current interpreter supports free-threading, :option:`python -VV <-V>`
and :data:`sys.version` contain "experimental free-threading build".
and :data:`sys.version` contain "free-threading build".
The new :func:`sys._is_gil_enabled` function can be used to check whether
the GIL is actually disabled in the running process.

2
Doc/howto/functional.rst
View file

@ -602,7 +602,7 @@ generators:
raise an exception inside the generator; the exception is raised by the
``yield`` expression where the generator's execution is paused.
* :meth:`~generator.close` raises a :exc:`GeneratorExit` exception inside the
* :meth:`~generator.close` sends a :exc:`GeneratorExit` exception to the
generator to terminate the iteration. On receiving this exception, the
generator's code must either raise :exc:`GeneratorExit` or
:exc:`StopIteration`; catching the exception and doing anything else is

2
Doc/howto/isolating-extensions.rst
View file

@ -453,7 +453,7 @@ Avoiding ``PyObject_New``
GC-tracked objects need to be allocated using GC-aware functions.
If you use use :c:func:`PyObject_New` or :c:func:`PyObject_NewVar`:
If you use :c:func:`PyObject_New` or :c:func:`PyObject_NewVar`:
- Get and call type's :c:member:`~PyTypeObject.tp_alloc` slot, if possible.
That is, replace ``TYPE *o = PyObject_New(TYPE, typeobj)`` with::

4
Doc/howto/perf_profiling.rst
View file

@ -92,7 +92,7 @@ Then we can use ``perf report`` to analyze the data:
| | | |
| | | |--51.67%--_PyEval_EvalFrameDefault
| | | | |
| | | | |--11.52%--_PyLong_Add
| | | | |--11.52%--_PyCompactLong_Add
| | | | | |
| | | | | |--2.97%--_PyObject_Malloc
...
@ -142,7 +142,7 @@ Instead, if we run the same experiment with ``perf`` support enabled we get:
| | | |
| | | |--51.81%--_PyEval_EvalFrameDefault
| | | | |
| | | | |--13.77%--_PyLong_Add
| | | | |--13.77%--_PyCompactLong_Add
| | | | | |
| | | | | |--3.26%--_PyObject_Malloc

8
Doc/howto/regex.rst
View file

@ -1016,7 +1016,9 @@ extension. This regular expression matches ``foo.bar`` and
Now, consider complicating the problem a bit; what if you want to match
filenames where the extension is not ``bat``? Some incorrect attempts:
``.*[.][^b].*$`` The first attempt above tries to exclude ``bat`` by requiring
``.*[.][^b].*$``
The first attempt above tries to exclude ``bat`` by requiring
that the first character of the extension is not a ``b``. This is wrong,
because the pattern also doesn't match ``foo.bar``.
@ -1043,7 +1045,9 @@ confusing.
A negative lookahead cuts through all this confusion:
``.*[.](?!bat$)[^.]*$`` The negative lookahead means: if the expression ``bat``
``.*[.](?!bat$)[^.]*$``
The negative lookahead means: if the expression ``bat``
doesn't match at this point, try the rest of the pattern; if ``bat$`` does
match, the whole pattern will fail. The trailing ``$`` is required to ensure
that something like ``sample.batch``, where the extension only starts with

2
Doc/library/argparse.rst
View file

@ -955,7 +955,7 @@ See also :ref:`specifying-ambiguous-arguments`. The supported values are:
.. index:: single: + (plus); in argparse module
* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
* ``'+'``. Just like ``'*'``, all command-line arguments present are gathered into a
list. Additionally, an error message will be generated if there wasn't at
least one command-line argument present. For example::

2
Doc/library/calendar.rst
View file

@ -251,7 +251,7 @@ interpreted as prescribed by the ISO 8601 standard. Year 0 is 1 BC, year -1 is
3) specifies the number of months per row. *css* is the name for the
cascading style sheet to be used. :const:`None` can be passed if no style
sheet should be used. *encoding* specifies the encoding to be used for the
output (defaulting to the system default encoding).
output (defaulting to ``'utf-8'``).
.. method:: formatmonthname(theyear, themonth, withyear=True)

8
Doc/library/codecs.rst
View file

@ -53,6 +53,14 @@ any codec:
:exc:`UnicodeDecodeError`). Refer to :ref:`codec-base-classes` for more
information on codec error handling.
.. function:: charmap_build(string)
Return a mapping suitable for encoding with a custom single-byte encoding.
Given a :class:`str` *string* of up to 256 characters representing a
decoding table, returns either a compact internal mapping object
``EncodingMap`` or a :class:`dictionary <dict>` mapping character ordinals
to byte values. Raises a :exc:`TypeError` on invalid input.
The full details for each codec can also be looked up directly:
.. function:: lookup(encoding, /)

1
Doc/library/concurrency.rst
View file

@ -18,6 +18,7 @@ multitasking). Here's an overview:
multiprocessing.shared_memory.rst
concurrent.rst
concurrent.futures.rst
concurrent.interpreters.rst
subprocess.rst
sched.rst
queue.rst

19
Doc/library/concurrent.futures.rst
View file

@ -265,7 +265,7 @@ Each worker's interpreter is isolated from all the other interpreters.
"Isolated" means each interpreter has its own runtime state and
operates completely independently. For example, if you redirect
:data:`sys.stdout` in one interpreter, it will not be automatically
redirected any other interpreter. If you import a module in one
redirected to any other interpreter. If you import a module in one
interpreter, it is not automatically imported in any other. You
would need to import the module separately in interpreter where
you need it. In fact, each module imported in an interpreter is
@ -287,7 +287,7 @@ efficient alternative is to serialize with :mod:`pickle` and then send
the bytes over a shared :mod:`socket <socket>` or
:func:`pipe <os.pipe>`.
.. class:: InterpreterPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=(), shared=None)
.. class:: InterpreterPoolExecutor(max_workers=None, thread_name_prefix='', initializer=None, initargs=())
A :class:`ThreadPoolExecutor` subclass that executes calls asynchronously
using a pool of at most *max_workers* threads. Each thread runs
@ -304,21 +304,10 @@ the bytes over a shared :mod:`socket <socket>` or
and *initargs* using :mod:`pickle` when sending them to the worker's
interpreter.
.. note::
Functions defined in the ``__main__`` module cannot be pickled
and thus cannot be used.
.. note::
The executor may replace uncaught exceptions from *initializer*
with :class:`~concurrent.futures.interpreter.ExecutionFailed`.
The optional *shared* argument is a :class:`dict` of objects that all
interpreters in the pool share. The *shared* items are added to each
interpreter's ``__main__`` module. Not all objects are shareable.
Shareable objects include the builtin singletons, :class:`str`
and :class:`bytes`, and :class:`memoryview`. See :pep:`734`
for more info.
Other caveats from parent :class:`ThreadPoolExecutor` apply here.
:meth:`~Executor.submit` and :meth:`~Executor.map` work like normal,
@ -326,10 +315,6 @@ except the worker serializes the callable and arguments using
:mod:`pickle` when sending them to its interpreter. The worker
likewise serializes the return value when sending it back.
.. note::
Functions defined in the ``__main__`` module cannot be pickled
and thus cannot be used.
When a worker's current task raises an uncaught exception, the worker
always tries to preserve the exception as-is. If that is successful
then it also sets the ``__cause__`` to a corresponding

387
Doc/library/concurrent.interpreters.rst Normal file
View file

@ -0,0 +1,387 @@
:mod:`!concurrent.interpreters` --- Multiple interpreters in the same process
=============================================================================
.. module:: concurrent.interpreters
:synopsis: Multiple interpreters in the same process
.. moduleauthor:: Eric Snow <ericsnowcurrently@gmail.com>
.. sectionauthor:: Eric Snow <ericsnowcurrently@gmail.com>
.. versionadded:: 3.14
**Source code:** :source:`Lib/concurrent/interpreters.py`
--------------
The :mod:`!concurrent.interpreters` module constructs higher-level
interfaces on top of the lower level :mod:`!_interpreters` module.
The module is primarily meant to provide a basic API for managing
interpreters (AKA "subinterpreters") and running things in them.
Running mostly involves switching to an interpreter (in the current
thread) and calling a function in that execution context.
For concurrency, interpreters themselves (and this module) don't
provide much more than isolation, which on its own isn't useful.
Actual concurrency is available separately through
:mod:`threads <threading>` See `below <interp-concurrency_>`_
.. seealso::
:class:`~concurrent.futures.InterpreterPoolExecutor`
combines threads with interpreters in a familiar interface.
.. XXX Add references to the upcoming HOWTO docs in the seealso block.
:ref:`isolating-extensions-howto`
how to update an extension module to support multiple interpreters
:pep:`554`
:pep:`734`
:pep:`684`
.. XXX Why do we disallow multiple interpreters on WASM?
.. include:: ../includes/wasm-notavail.rst
Key details
-----------
Before we dive in further, there are a small number of details
to keep in mind about using multiple interpreters:
* `isolated <interp-isolation_>`_, by default
* no implicit threads
* not all PyPI packages support use in multiple interpreters yet
.. XXX Are there other relevant details to list?
.. _interpreters-intro:
Introduction
------------
An "interpreter" is effectively the execution context of the Python
runtime. It contains all of the state the runtime needs to execute
a program. This includes things like the import state and builtins.
(Each thread, even if there's only the main thread, has some extra
runtime state, in addition to the current interpreter, related to
the current exception and the bytecode eval loop.)
The concept and functionality of the interpreter have been a part of
Python since version 2.2, but the feature was only available through
the C-API and not well known, and the `isolation <interp-isolation_>`_
was relatively incomplete until version 3.12.
.. _interp-isolation:
Multiple Interpreters and Isolation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A Python implementation may support using multiple interpreters in the
same process. CPython has this support. Each interpreter is
effectively isolated from the others (with a limited number of
carefully managed process-global exceptions to the rule).
That isolation is primarily useful as a strong separation between
distinct logical components of a program, where you want to have
careful control of how those components interact.
.. note::
Interpreters in the same process can technically never be strictly
isolated from one another since there are few restrictions on memory
access within the same process. The Python runtime makes a best
effort at isolation but extension modules may easily violate that.
Therefore, do not use multiple interpreters in security-sensitive
situations, where they shouldn't have access to each other's data.
Running in an Interpreter
^^^^^^^^^^^^^^^^^^^^^^^^^
Running in a different interpreter involves switching to it in the
current thread and then calling some function. The runtime will
execute the function using the current interpreter's state. The
:mod:`!concurrent.interpreters` module provides a basic API for
creating and managing interpreters, as well as the switch-and-call
operation.
No other threads are automatically started for the operation.
There is `a helper <interp-call-in-thread_>`_ for that though.
There is another dedicated helper for calling the builtin
:func:`exec` in an interpreter.
When :func:`exec` (or :func:`eval`) are called in an interpreter,
they run using the interpreter's :mod:`!__main__` module as the
"globals" namespace. The same is true for functions that aren't
associated with any module. This is the same as how scripts invoked
from the command-line run in the :mod:`!__main__` module.
.. _interp-concurrency:
Concurrency and Parallelism
^^^^^^^^^^^^^^^^^^^^^^^^^^^
As noted earlier, interpreters do not provide any concurrency
on their own. They strictly represent the isolated execution
context the runtime will use *in the current thread*. That isolation
makes them similar to processes, but they still enjoy in-process
efficiency, like threads.
All that said, interpreters do naturally support certain flavors of
concurrency, as a powerful side effect of that isolation.
There's a powerful side effect of that isolation. It enables a
different approach to concurrency than you can take with async or
threads. It's a similar concurrency model to CSP or the actor model,
a model which is relatively easy to reason about.
You can take advantage of that concurrency model in a single thread,
switching back and forth between interpreters, Stackless-style.
However, this model is more useful when you combine interpreters
with multiple threads. This mostly involves starting a new thread,
where you switch to another interpreter and run what you want there.
Each actual thread in Python, even if you're only running in the main
thread, has its own *current* execution context. Multiple threads can
use the same interpreter or different ones.
At a high level, you can think of the combination of threads and
interpreters as threads with opt-in sharing.
As a significant bonus, interpreters are sufficiently isolated that
they do not share the :term:`GIL`, which means combining threads with
multiple interpreters enables full multi-core parallelism.
(This has been the case since Python 3.12.)
Communication Between Interpreters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In practice, multiple interpreters are useful only if we have a way
to communicate between them. This usually involves some form of
message passing, but can even mean sharing data in some carefully
managed way.
With this in mind, the :mod:`!concurrent.interpreters` module provides
a :class:`queue.Queue` implementation, available through
:func:`create_queue`.
.. _interp-object-sharing:
"Sharing" Objects
^^^^^^^^^^^^^^^^^
Any data actually shared between interpreters loses the thread-safety
provided by the :term:`GIL`. There are various options for dealing with
this in extension modules. However, from Python code the lack of
thread-safety means objects can't actually be shared, with a few
exceptions. Instead, a copy must be created, which means mutable
objects won't stay in sync.
By default, most objects are copied with :mod:`pickle` when they are
passed to another interpreter. Nearly all of the immutable builtin
objects are either directly shared or copied efficiently. For example:
* :const:`None`
* :class:`bool` (:const:`True` and :const:`False`)
* :class:`bytes`
* :class:`str`
* :class:`int`
* :class:`float`
* :class:`tuple` (of similarly supported objects)
There is a small number of Python types that actually share mutable
data between interpreters:
* :class:`memoryview`
* :class:`Queue`
Reference
---------
This module defines the following functions:
.. function:: list_all()
Return a :class:`list` of :class:`Interpreter` objects,
one for each existing interpreter.
.. function:: get_current()
Return an :class:`Interpreter` object for the currently running
interpreter.
.. function:: get_main()
Return an :class:`Interpreter` object for the main interpreter.
This is the interpreter the runtime created to run the :term:`REPL`
or the script given at the command-line. It is usually the only one.
.. function:: create()
Initialize a new (idle) Python interpreter
and return a :class:`Interpreter` object for it.
.. function:: create_queue()
Initialize a new cross-interpreter queue and return a :class:`Queue`
object for it.
Interpreter objects
^^^^^^^^^^^^^^^^^^^
.. class:: Interpreter(id)
A single interpreter in the current process.
Generally, :class:`Interpreter` shouldn't be called directly.
Instead, use :func:`create` or one of the other module functions.
.. attribute:: id
(read-only)
The underlying interpreter's ID.
.. attribute:: whence
(read-only)
A string describing where the interpreter came from.
.. method:: is_running()
Return ``True`` if the interpreter is currently executing code
in its :mod:`!__main__` module and ``False`` otherwise.
.. method:: close()
Finalize and destroy the interpreter.
.. method:: prepare_main(ns=None, **kwargs)
Bind objects in the interpreter's :mod:`!__main__` module.
Some objects are actually shared and some are copied efficiently,
but most are copied via :mod:`pickle`. See :ref:`interp-object-sharing`.
.. method:: exec(code, /, dedent=True)
Run the given source code in the interpreter (in the current thread).
.. method:: call(callable, /, *args, **kwargs)
Return the result of calling running the given function in the
interpreter (in the current thread).
.. _interp-call-in-thread:
.. method:: call_in_thread(callable, /, *args, **kwargs)
Run the given function in the interpreter (in a new thread).
Exceptions
^^^^^^^^^^
.. exception:: InterpreterError
This exception, a subclass of :exc:`Exception`, is raised when
an interpreter-related error happens.
.. exception:: InterpreterNotFoundError
This exception, a subclass of :exc:`InterpreterError`, is raised when
the targeted interpreter no longer exists.
.. exception:: ExecutionFailed
This exception, a subclass of :exc:`InterpreterError`, is raised when
the running code raised an uncaught exception.
.. attribute:: excinfo
A basic snapshot of the exception raised in the other interpreter.
.. XXX Document the excinfoattrs?
.. exception:: NotShareableError
This exception, a subclass of :exc:`TypeError`, is raised when
an object cannot be sent to another interpreter.
Communicating Between Interpreters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. class:: Queue(id)
A wrapper around a low-level, cross-interpreter queue, which
implements the :class:`queue.Queue` interface. The underlying queue
can only be created through :func:`create_queue`.
Some objects are actually shared and some are copied efficiently,
but most are copied via :mod:`pickle`. See :ref:`interp-object-sharing`.
.. attribute:: id
(read-only)
The queue's ID.
.. exception:: QueueEmptyError
This exception, a subclass of :exc:`queue.Empty`, is raised from
:meth:`!Queue.get` and :meth:`!Queue.get_nowait` when the queue
is empty.
.. exception:: QueueFullError
This exception, a subclass of :exc:`queue.Full`, is raised from
:meth:`!Queue.put` and :meth:`!Queue.put_nowait` when the queue
is full.
Basic usage
-----------
Creating an interpreter and running code in it::
from concurrent import interpreters
interp = interpreters.create()
# Run in the current OS thread.
interp.exec('print("spam!")')
interp.exec("""if True:
print('spam!')
""")
from textwrap import dedent
interp.exec(dedent("""
print('spam!')
"""))
def run(arg):
return arg
res = interp.call(run, 'spam!')
print(res)
def run():
print('spam!')
interp.call(run)
# Run in new OS thread.
t = interp.call_in_thread(run)
t.join()

3
Doc/library/concurrent.rst
View file

@ -1,6 +1,7 @@
The :mod:`!concurrent` package
==============================
Currently, there is only one module in this package:
This package contains the following modules:
* :mod:`concurrent.futures` -- Launching parallel tasks
* :mod:`concurrent.interpreters` -- Multiple interpreters in the same process

44
Doc/library/csv.rst
View file

@ -53,7 +53,7 @@ The :mod:`csv` module defines the following functions:
.. index::
single: universal newlines; csv.reader function
.. function:: reader(csvfile, dialect='excel', **fmtparams)
.. function:: reader(csvfile, /, dialect='excel', **fmtparams)
Return a :ref:`reader object <reader-objects>` that will process
lines from the given *csvfile*. A csvfile must be an iterable of
@ -84,7 +84,7 @@ The :mod:`csv` module defines the following functions:
Spam, Lovely Spam, Wonderful Spam
.. function:: writer(csvfile, dialect='excel', **fmtparams)
.. function:: writer(csvfile, /, dialect='excel', **fmtparams)
Return a writer object responsible for converting the user's data into delimited
strings on the given file-like object. *csvfile* can be any object with a
@ -323,8 +323,8 @@ The :mod:`csv` module defines the following constants:
.. data:: QUOTE_MINIMAL
Instructs :class:`writer` objects to only quote those fields which contain
special characters such as *delimiter*, *quotechar* or any of the characters in
*lineterminator*.
special characters such as *delimiter*, *quotechar*, ``'\r'``, ``'\n'``
or any of the characters in *lineterminator*.
.. data:: QUOTE_NONNUMERIC
@ -342,10 +342,13 @@ The :mod:`csv` module defines the following constants:
.. data:: QUOTE_NONE
Instructs :class:`writer` objects to never quote fields. When the current
*delimiter* occurs in output data it is preceded by the current *escapechar*
character. If *escapechar* is not set, the writer will raise :exc:`Error` if
Instructs :class:`writer` objects to never quote fields.
When the current *delimiter*, *quotechar*, *escapechar*, ``'\r'``, ``'\n'``
or any of the characters in *lineterminator* occurs in output data
it is preceded by the current *escapechar* character.
If *escapechar* is not set, the writer will raise :exc:`Error` if
any characters that require escaping are encountered.
Set *quotechar* to ``None`` to prevent its escaping.
Instructs :class:`reader` objects to perform no special processing of quote characters.
@ -414,9 +417,16 @@ Dialects support the following attributes:
.. attribute:: Dialect.escapechar
A one-character string used by the writer to escape the *delimiter* if *quoting*
is set to :const:`QUOTE_NONE` and the *quotechar* if *doublequote* is
:const:`False`. On reading, the *escapechar* removes any special meaning from
A one-character string used by the writer to escape characters that
require escaping:
* the *delimiter*, the *quotechar*, ``'\r'``, ``'\n'`` and any of the
characters in *lineterminator* are escaped if *quoting* is set to
:const:`QUOTE_NONE`;
* the *quotechar* is escaped if *doublequote* is :const:`False`;
* the *escapechar* itself.
On reading, the *escapechar* removes any special meaning from
the following character. It defaults to :const:`None`, which disables escaping.
.. versionchanged:: 3.11
@ -436,9 +446,12 @@ Dialects support the following attributes:
.. attribute:: Dialect.quotechar
A one-character string used to quote fields containing special characters, such
as the *delimiter* or *quotechar*, or which contain new-line characters. It
defaults to ``'"'``.
A one-character string used to quote fields containing special characters,
such as the *delimiter* or the *quotechar*, or which contain new-line
characters (``'\r'``, ``'\n'`` or any of the characters in *lineterminator*).
It defaults to ``'"'``.
Can be set to ``None`` to prevent escaping ``'"'`` if *quoting* is set
to :const:`QUOTE_NONE`.
.. versionchanged:: 3.11
An empty *quotechar* is not allowed.
@ -447,7 +460,8 @@ Dialects support the following attributes:
Controls when quotes should be generated by the writer and recognised by the
reader. It can take on any of the :ref:`QUOTE_\* constants <csv-constants>`
and defaults to :const:`QUOTE_MINIMAL`.
and defaults to :const:`QUOTE_MINIMAL` if *quotechar* is not ``None``,
and :const:`QUOTE_NONE` otherwise.
.. attribute:: Dialect.skipinitialspace
@ -609,7 +623,7 @@ A slightly more advanced use of the reader --- catching and reporting errors::
for row in reader:
print(row)
except csv.Error as e:
sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))
sys.exit(f'file {filename}, line {reader.line_num}: {e}')
And while the module doesn't directly support parsing strings, it can easily be
done::

16
Doc/library/ctypes.rst
View file

@ -714,10 +714,16 @@ item in the :attr:`~Structure._fields_` tuples::
... ("second_16", c_int, 16)]
...
>>> print(Int.first_16)
<Field type=c_long, ofs=0:0, bits=16>
<ctypes.CField 'first_16' type=c_int, ofs=0, bit_size=16, bit_offset=0>
>>> print(Int.second_16)
<Field type=c_long, ofs=0:16, bits=16>
>>>
<ctypes.CField 'second_16' type=c_int, ofs=0, bit_size=16, bit_offset=16>
It is important to note that bit field allocation and layout in memory are not
defined as a C standard; their implementation is compiler-specific.
By default, Python will attempt to match the behavior of a "native" compiler
for the current platform.
See the :attr:`~Structure._layout_` attribute for details on the default
behavior and how to change it.
.. _ctypes-arrays:
@ -876,7 +882,7 @@ invalid non-\ ``NULL`` pointers would crash Python)::
Thread safety without the GIL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In Python 3.13, the :term:`GIL` may be disabled on :term:`experimental free threaded <free threading>` builds.
From Python 3.13 onward, the :term:`GIL` can be disabled on :term:`free threaded <free threading>` builds.
In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects:
.. code-block:: pycon
@ -2959,7 +2965,7 @@ fields, or any other data types containing pointer type fields.
.. attribute:: is_anonymous
True if this field is anonymous, that is, it contains nested sub-fields
that should be be merged into a containing structure or union.
that should be merged into a containing structure or union.
.. _ctypes-arrays-pointers:

7
Doc/library/dataclasses.rst
View file

@ -121,8 +121,11 @@ Module contents
:meth:`!__le__`, :meth:`!__gt__`, or :meth:`!__ge__`, then
:exc:`TypeError` is raised.
- *unsafe_hash*: If ``False`` (the default), a :meth:`~object.__hash__` method
is generated according to how *eq* and *frozen* are set.
- *unsafe_hash*: If true, force ``dataclasses`` to create a
:meth:`~object.__hash__` method, even though it may not be safe to do so.
Otherwise, generate a :meth:`~object.__hash__` method according to how
*eq* and *frozen* are set.
The default value is ``False``.
:meth:`!__hash__` is used by built-in :meth:`hash`, and when objects are
added to hashed collections such as dictionaries and sets. Having a

2
Doc/library/dialog.rst
View file

@ -220,7 +220,7 @@ is the base class for dialogs defined in other supporting modules.
.. class:: Dialog(master=None, **options)
.. method:: show(color=None, **options)
.. method:: show(**options)
Render the Dialog window.

8
Doc/library/dis.rst
View file

@ -1094,14 +1094,6 @@ iterations of the loop.
.. versionadded:: 3.14
.. opcode:: LOAD_CONST_IMMORTAL (consti)
Pushes ``co_consts[consti]`` onto the stack.
Can be used when the constant value is known to be immortal.
.. versionadded:: 3.14
.. opcode:: LOAD_NAME (namei)
Pushes the value associated with ``co_names[namei]`` onto the stack.

34
Doc/library/email.header.rst
View file

@ -178,16 +178,36 @@ The :mod:`email.header` module also provides the following convenient functions.
Decode a message header value without converting the character set. The header
value is in *header*.
This function returns a list of ``(decoded_string, charset)`` pairs containing
each of the decoded parts of the header. *charset* is ``None`` for non-encoded
parts of the header, otherwise a lower case string containing the name of the
character set specified in the encoded string.
For historical reasons, this function may return either:
Here's an example::
1. A list of pairs containing each of the decoded parts of the header,
``(decoded_bytes, charset)``, where *decoded_bytes* is always an instance of
:class:`bytes`, and *charset* is either:
- A lower case string containing the name of the character set specified.
- ``None`` for non-encoded parts of the header.
2. A list of length 1 containing a pair ``(string, None)``, where
*string* is always an instance of :class:`str`.
An :exc:`email.errors.HeaderParseError` may be raised when certain decoding
errors occur (e.g. a base64 decoding exception).
Here are examples:
>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]
>>> decode_header('unencoded_string')
[('unencoded_string', None)]
>>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
[(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]
.. note::
This function exists for backwards compatibility only. For
new code, we recommend using :class:`email.headerregistry.HeaderRegistry`.
.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')
@ -203,3 +223,7 @@ The :mod:`email.header` module also provides the following convenient functions.
:class:`Header` instance. Optional *maxlinelen*, *header_name*, and
*continuation_ws* are as in the :class:`Header` constructor.
.. note::
This function exists for backwards compatibility only, and is
not recommended for use in new code.

11
Doc/library/exceptions.rst
View file

@ -429,7 +429,9 @@ The following exceptions are the exceptions that are usually raised.
* Creating a new Python thread.
* :meth:`Joining <threading.Thread.join>` a running daemon thread.
* :func:`os.fork`.
* :func:`os.fork`,
* acquiring a lock such as :class:`threading.Lock`, when it is known that
the operation would otherwise deadlock.
See also the :func:`sys.is_finalizing` function.
@ -440,6 +442,11 @@ The following exceptions are the exceptions that are usually raised.
:meth:`threading.Thread.join` can now raise this exception.
.. versionchanged:: next
This exception may be raised when acquiring :meth:`threading.Lock`
or :meth:`threading.RLock`.
.. exception:: RecursionError
This exception is derived from :exc:`RuntimeError`. It is raised when the
@ -1048,7 +1055,7 @@ their subgroups based on the types of the contained exceptions.
subclasses that need a different constructor signature need to
override that rather than :meth:`~object.__init__`. For example, the following
defines an exception group subclass which accepts an exit_code and
and constructs the group's message from it. ::
constructs the group's message from it. ::
class Errors(ExceptionGroup):
def __new__(cls, errors, exit_code):

39
Doc/library/faulthandler.rst
View file

@ -90,7 +90,7 @@ An error will be printed instead of the stack.
Additionally, some compilers do not support :term:`CPython's <CPython>`
implementation of C stack dumps. As a result, a different error may be printed
instead of the stack, even if the the operating system supports dumping stacks.
instead of the stack, even if the operating system supports dumping stacks.
.. note::
@ -228,6 +228,41 @@ handler:
Fatal Python error: Segmentation fault
Current thread 0x00007fb899f39700 (most recent call first):
File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
File "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at
File "<stdin>", line 1 in <module>
Current thread's C stack trace (most recent call first):
Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e]
Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd]
Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a]
Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0]
Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c]
Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6]
Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976]
Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c]
Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e]
Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624]
Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883]
Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6]
Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04]
Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302]
Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3]
Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957]
Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4]
Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634]
Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1]
Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348]
Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626]
Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e]
Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a]
Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8]
Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b]
Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe]
<truncated rest of calls>
Segmentation fault

2
Doc/library/fractions.rst
View file

@ -142,7 +142,7 @@ another rational number, or from a string.
.. versionadded:: 3.12
.. classmethod:: from_float(flt)
.. classmethod:: from_float(f)
Alternative constructor which only accepts instances of
:class:`float` or :class:`numbers.Integral`. Beware that

10
Doc/library/functions.rst
View file

@ -1839,15 +1839,15 @@ are always available. They are listed here in alphabetical order.
``range(start, stop, step)``. The *start* and *step* arguments default to
``None``.
Slice objects have read-only data attributes :attr:`!start`,
:attr:`!stop`, and :attr:`!step` which merely return the argument
values (or their default). They have no other explicit functionality;
however, they are used by NumPy and other third-party packages.
.. attribute:: slice.start
.. attribute:: slice.stop
.. attribute:: slice.step
Slice objects have read-only data attributes :attr:`!start`,
:attr:`!stop`, and :attr:`!step` which merely return the argument
values (or their default). They have no other explicit functionality;
however, they are used by NumPy and other third-party packages.
Slice objects are also generated when extended indexing syntax is used. For
example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See
:func:`itertools.islice` for an alternate version that returns an

4
Doc/library/logging.config.rst
View file

@ -548,7 +548,7 @@ mnemonic that the corresponding value is a callable.
The ``filters`` member of ``handlers`` and ``loggers`` can take
filter instances in addition to ids.
You can also specify a special key ``'.'`` whose value is a dictionary is a
You can also specify a special key ``'.'`` whose value is a
mapping of attribute names to values. If found, the specified attributes will
be set on the user-defined object before it is returned. Thus, with the
following configuration::
@ -586,7 +586,7 @@ configuration dictionary for the handler named ``foo``, and later (once that
handler has been configured) it points to the configured handler instance.
Thus, ``cfg://handlers.foo`` could resolve to either a dictionary or a handler
instance. In general, it is wise to name handlers in a way such that dependent
handlers are configured _after_ any handlers they depend on; that allows
handlers are configured *after* any handlers they depend on; that allows
something like ``cfg://handlers.foo`` to be used in configuring a handler that
depends on handler ``foo``. If that dependent handler were named ``bar``,
problems would result, because the configuration of ``bar`` would be attempted

9
Doc/library/logging.handlers.rst
View file

@ -1059,6 +1059,15 @@ possible, while any potentially slow operations (such as sending an email via
.. note:: If you are using :mod:`multiprocessing`, you should avoid using
:class:`~queue.SimpleQueue` and instead use :class:`multiprocessing.Queue`.
.. warning::
The :mod:`multiprocessing` module uses an internal logger created and
accessed via :meth:`~multiprocessing.get_logger`.
:class:`multiprocessing.Queue` will log ``DEBUG`` level messages upon
items being queued. If those log messages are processed by a
:class:`QueueHandler` using the same :class:`multiprocessing.Queue` instance,
it will cause a deadlock or infinite recursion.
.. method:: emit(record)
Enqueues the result of preparing the LogRecord. Should an exception

16
Doc/library/math.rst
View file

@ -59,6 +59,7 @@ noted otherwise, all return values are floats.
:func:`isnan(x) <isnan>` Check if *x* is a NaN (not a number)
:func:`ldexp(x, i) <ldexp>` ``x * (2**i)``, inverse of function :func:`frexp`
:func:`nextafter(x, y, steps) <nextafter>` Floating-point value *steps* steps after *x* towards *y*
:func:`signbit(x) <signbit>` Check if *x* is a negative number
:func:`ulp(x) <ulp>` Value of the least significant bit of *x*
**Power, exponential and logarithmic functions**
@ -387,8 +388,8 @@ Floating point manipulation functions
.. function:: issubnormal(x)
Return ``True`` if *x* is a subnormal number, that is a finite
nonzero number with a magnitude smaller than the smallest positive normal
number, see :data:`sys.float_info.min`. Return ``False`` otherwise.
nonzero number with a magnitude smaller than :data:`sys.float_info.min`.
Return ``False`` otherwise.
.. versionadded:: next
@ -431,6 +432,15 @@ Floating point manipulation functions
Added the *steps* argument.
.. function:: signbit(x)
Return ``True`` if the sign of *x* is negative and ``False`` otherwise.
This is useful to detect the sign bit of zeroes, infinities and NaNs.
.. versionadded:: next
.. function:: ulp(x)
Return the value of the least significant bit of the float *x*:
@ -794,7 +804,7 @@ Constants
The mathematical constant *τ* = 6.283185..., to available precision.
Tau is a circle constant equal to 2\ *π*, the ratio of a circle's circumference to
its radius. To learn more about Tau, check out Vi Hart's video `Pi is (still)
Wrong <https://www.youtube.com/watch?v=jG7vhMMXagQ>`_, and start celebrating
Wrong <https://vimeo.com/147792667>`_, and start celebrating
`Tau day <https://tauday.com/>`_ by eating twice as much pie!
.. versionadded:: 3.6

2
Doc/library/mmap.rst
View file

@ -269,7 +269,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length
Resizing a map created with *access* of :const:`ACCESS_READ` or
:const:`ACCESS_COPY`, will raise a :exc:`TypeError` exception.
Resizing a map created with with *trackfd* set to ``False``,
Resizing a map created with *trackfd* set to ``False``,
will raise a :exc:`ValueError` exception.
**On Windows**: Resizing the map will raise an :exc:`OSError` if there are other

4
Doc/library/netrc.rst
View file

@ -24,12 +24,14 @@ the Unix :program:`ftp` program and other FTP clients.
a :exc:`FileNotFoundError` exception will be raised.
Parse errors will raise :exc:`NetrcParseError` with diagnostic
information including the file name, line number, and terminating token.
If no argument is specified on a POSIX system, the presence of passwords in
the :file:`.netrc` file will raise a :exc:`NetrcParseError` if the file
ownership or permissions are insecure (owned by a user other than the user
running the process, or accessible for read or write by any other user).
This implements security behavior equivalent to that of ftp and other
programs that use :file:`.netrc`.
programs that use :file:`.netrc`. Such security checks are not available
on platforms that do not support :func:`os.getuid`.
.. versionchanged:: 3.4 Added the POSIX permission check.

2
Doc/library/pathlib.rst
View file

@ -1985,7 +1985,7 @@ The :mod:`pathlib.types` module provides types for static type checking.
If *follow_symlinks* is ``False``, return ``True`` only if the path
is a file (without following symlinks); return ``False`` if the path
is a directory or other other non-file, or if it doesn't exist.
is a directory or other non-file, or if it doesn't exist.
.. method:: is_symlink()

4
Doc/library/pkgutil.rst
View file

@ -69,8 +69,8 @@ support.
Yield :term:`finder` objects for the given module name.
If fullname contains a ``'.'``, the finders will be for the package
containing fullname, otherwise they will be all registered top level
If *fullname* contains a ``'.'``, the finders will be for the package
containing *fullname*, otherwise they will be all registered top level
finders (i.e. those on both :data:`sys.meta_path` and :data:`sys.path_hooks`).
If the named module is in a package, that package is imported as a side

5
Doc/library/python.rst
View file

@ -27,3 +27,8 @@ overview:
inspect.rst
annotationlib.rst
site.rst
.. seealso::
* See the :mod:`concurrent.interpreters` module, which similarly
exposes core runtime functionality.

11
Doc/library/shutil.rst
View file

@ -47,6 +47,13 @@ Directory and files operations
0, only the contents from the current file position to the end of the file will
be copied.
:func:`copyfileobj` will *not* guarantee that the destination stream has
been flushed on completion of the copy. If you want to read from the
destination at the completion of the copy operation (for example, reading
the contents of a temporary file that has been copied from a HTTP stream),
you must ensure that you have called :func:`~io.IOBase.flush` or
:func:`~io.IOBase.close` on the file-like object before attempting to read
the destination file.
.. function:: copyfile(src, dst, *, follow_symlinks=True)
@ -327,6 +334,10 @@ Directory and files operations
The deprecated *onerror* is similar to *onexc*, except that the third
parameter it receives is the tuple returned from :func:`sys.exc_info`.
.. seealso::
:ref:`shutil-rmtree-example` for an example of handling the removal
of a directory tree that contains read-only files.
.. audit-event:: shutil.rmtree path,dir_fd shutil.rmtree
.. versionchanged:: 3.3

2
Doc/library/socketserver.rst
View file

@ -543,7 +543,7 @@ objects that simplify communication by providing the standard file interface)::
The difference is that the ``readline()`` call in the second handler will call
``recv()`` multiple times until it encounters a newline character, while the
the first handler had to use a ``recv()`` loop to accumulate data until a
first handler had to use a ``recv()`` loop to accumulate data until a
newline itself. If it had just used a single ``recv()`` without the loop it
would just have returned what has been received so far from the client.
TCP is stream based: data arrives in the order it was sent, but there no

31
Doc/library/sqlite3.rst
View file

@ -507,6 +507,15 @@ Module constants
Version number of the runtime SQLite library as a :class:`tuple` of
:class:`integers <int>`.
.. data:: SQLITE_KEYWORDS
A :class:`tuple` containing all sqlite3 keywords.
This constant is only available if Python was compiled with SQLite
3.24.0 or greater.
.. versionadded:: next
.. data:: threadsafety
Integer constant required by the DB-API 2.0, stating the level of thread
@ -1482,7 +1491,9 @@ Cursor objects
:type parameters: :class:`dict` | :term:`sequence`
:raises ProgrammingError:
If *sql* contains more than one SQL statement.
When *sql* contains more than one SQL statement.
When :ref:`named placeholders <sqlite3-placeholders>` are used
and *parameters* is a sequence instead of a :class:`dict`.
If :attr:`~Connection.autocommit` is
:data:`LEGACY_TRANSACTION_CONTROL`,
@ -1491,13 +1502,11 @@ Cursor objects
and there is no open transaction,
a transaction is implicitly opened before executing *sql*.
.. deprecated-removed:: 3.12 3.14
.. versionchanged:: 3.14
:exc:`DeprecationWarning` is emitted if
:exc:`ProgrammingError` is emitted if
:ref:`named placeholders <sqlite3-placeholders>` are used
and *parameters* is a sequence instead of a :class:`dict`.
Starting with Python 3.14, :exc:`ProgrammingError` will
be raised instead.
Use :meth:`executescript` to execute multiple SQL statements.
@ -1519,8 +1528,10 @@ Cursor objects
:type parameters: :term:`iterable`
:raises ProgrammingError:
If *sql* contains more than one SQL statement,
or is not a DML statement.
When *sql* contains more than one SQL statement
or is not a DML statement,
When :ref:`named placeholders <sqlite3-placeholders>` are used
and the items in *parameters* are sequences instead of :class:`dict`\s.
Example:
@ -1544,14 +1555,12 @@ Cursor objects
.. _RETURNING clauses: https://www.sqlite.org/lang_returning.html
.. deprecated-removed:: 3.12 3.14
.. versionchanged:: 3.14
:exc:`DeprecationWarning` is emitted if
:exc:`ProgrammingError` is emitted if
:ref:`named placeholders <sqlite3-placeholders>` are used
and the items in *parameters* are sequences
instead of :class:`dict`\s.
Starting with Python 3.14, :exc:`ProgrammingError` will
be raised instead.
.. method:: executescript(sql_script, /)

32
Doc/library/stdtypes.rst
View file

@ -1018,7 +1018,7 @@ operations have the same priority as the corresponding numeric operations. [3]_
| ``s * n`` or | equivalent to adding *s* to | (2)(7) |
| ``n * s`` | itself *n* times | |
+--------------------------+--------------------------------+----------+
| ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) |
| ``s[i]`` | *i*\ th item of *s*, origin 0 | (3)(9) |
+--------------------------+--------------------------------+----------+
| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) |
+--------------------------+--------------------------------+----------+
@ -1150,6 +1150,9 @@ Notes:
without copying any data and with the returned index being relative to
the start of the sequence rather than the start of the slice.
(9)
An :exc:`IndexError` is raised if *i* is outside the sequence range.
.. _typesseq-immutable:
@ -1838,6 +1841,14 @@ expression support in the :mod:`re` module).
unless an encoding error actually occurs,
:ref:`devmode` is enabled
or a :ref:`debug build <debug-build>` is used.
For example::
>>> encoded_str_to_bytes = 'Python'.encode()
>>> type(encoded_str_to_bytes)
<class 'bytes'>
>>> encoded_str_to_bytes
b'Python'
.. versionchanged:: 3.1
Added support for keyword arguments.
@ -1852,7 +1863,19 @@ expression support in the :mod:`re` module).
Return ``True`` if the string ends with the specified *suffix*, otherwise return
``False``. *suffix* can also be a tuple of suffixes to look for. With optional
*start*, test beginning at that position. With optional *end*, stop comparing
at that position.
at that position. Using *start* and *end* is equivalent to
``str[start:end].endswith(suffix)``. For example::
>>> 'Python'.endswith('on')
True
>>> 'a tuple of suffixes'.endswith(('at', 'in'))
False
>>> 'a tuple of suffixes'.endswith(('at', 'es'))
True
>>> 'Python is amazing'.endswith('is', 0, 9)
True
See also :meth:`startswith` and :meth:`removesuffix`.
.. method:: str.expandtabs(tabsize=8)
@ -1868,12 +1891,15 @@ expression support in the :mod:`re` module).
(``\n``) or return (``\r``), it is copied and the current column is reset to
zero. Any other character is copied unchanged and the current column is
incremented by one regardless of how the character is represented when
printed.
printed. For example::
>>> '01\t012\t0123\t01234'.expandtabs()
'01 012 0123 01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01 012 0123 01234'
>>> print('01\t012\n0123\t01234'.expandtabs(4))
01 012
0123 01234
.. method:: str.find(sub[, start[, end]])

28
Doc/library/sys.rst
View file

@ -1185,6 +1185,15 @@ always available. Unless explicitly noted otherwise, all variables are read-only
``cache_tag`` is set to ``None``, it indicates that module caching should
be disabled.
*supports_isolated_interpreters* is a boolean value, whether
this implementation supports multiple isolated interpreters.
It is ``True`` for CPython on most platforms. Platforms with
this support implement the low-level :mod:`!_interpreters` module.
.. seealso::
:pep:`684`, :pep:`734`, and :mod:`concurrent.interpreters`.
:data:`sys.implementation` may contain additional attributes specific to
the Python implementation. These non-standard attributes must start with
an underscore, and are not described here. Regardless of its contents,
@ -1194,6 +1203,9 @@ always available. Unless explicitly noted otherwise, all variables are read-only
.. versionadded:: 3.3
.. versionchanged:: 3.14
Added ``supports_isolated_interpreters`` field.
.. note::
The addition of new required attributes must go through the normal PEP
@ -1933,6 +1945,22 @@ always available. Unless explicitly noted otherwise, all variables are read-only
interpreter is pre-release (alpha, beta, or release candidate) then the
local and remote interpreters must be the same exact version.
.. audit-event:: sys.remote_exec pid script_path
When the code is executed in the remote process, an
:ref:`auditing event <auditing>` ``sys.remote_exec`` is raised with
the *pid* and the path to the script file.
This event is raised in the process that called :func:`sys.remote_exec`.
.. audit-event:: cpython.remote_debugger_script script_path
When the script is executed in the remote process, an
:ref:`auditing event <auditing>`
``cpython.remote_debugger_script`` is raised
with the path in the remote process.
This event is raised in the remote process, not the one
that called :func:`sys.remote_exec`.
.. availability:: Unix, Windows.
.. versionadded:: 3.14

4
Doc/library/threading.rst
View file

@ -102,7 +102,7 @@ CPU-bound tasks, as only one thread can execute Python bytecode at a time.
Despite this, threads remain a useful tool for achieving concurrency in many
scenarios.
As of Python 3.13, experimental :term:`free-threaded <free threading>` builds
As of Python 3.13, :term:`free-threaded <free threading>` builds
can disable the GIL, enabling true parallel execution of threads, but this
feature is not available by default (see :pep:`703`).
@ -621,7 +621,7 @@ since it is impossible to detect the termination of alien threads.
an error to :meth:`~Thread.join` a thread before it has been started
and attempts to do so raise the same exception.
If an attempt is made to join a running daemonic thread in in late stages
If an attempt is made to join a running daemonic thread in late stages
of :term:`Python finalization <interpreter shutdown>` :meth:`!join`
raises a :exc:`PythonFinalizationError`.

7
Doc/library/time.rst
View file

@ -712,13 +712,18 @@ Functions
Clock:
* On Windows, call ``GetSystemTimeAsFileTime()``.
* On Windows, call ``GetSystemTimePreciseAsFileTime()``.
* Call ``clock_gettime(CLOCK_REALTIME)`` if available.
* Otherwise, call ``gettimeofday()``.
Use :func:`time_ns` to avoid the precision loss caused by the :class:`float`
type.
.. versionchanged:: 3.13
On Windows, calls ``GetSystemTimePreciseAsFileTime()`` instead of
``GetSystemTimeAsFileTime()``.
.. function:: time_ns() -> int

2
Doc/library/token.rst
View file

@ -51,7 +51,7 @@ The token constants are:
.. data:: NAME
Token value that indicates an :ref:`identifier <identifiers>`.
Note that keywords are also initially tokenized an ``NAME`` tokens.
Note that keywords are also initially tokenized as ``NAME`` tokens.
.. data:: NUMBER

33
Doc/library/uuid.rst
View file

@ -193,43 +193,52 @@ The :mod:`uuid` module defines the following functions:
.. function:: uuid1(node=None, clock_seq=None)
Generate a UUID from a host ID, sequence number, and the current time. If *node*
is not given, :func:`getnode` is used to obtain the hardware address. If
*clock_seq* is given, it is used as the sequence number; otherwise a random
14-bit sequence number is chosen.
Generate a UUID from a host ID, sequence number, and the current time
according to :rfc:`RFC 9562, §5.1 <9562#section-5.1>`.
When *node* is not specified, :func:`getnode` is used to obtain the hardware
address as a 48-bit positive integer. When a sequence number *clock_seq* is
not specified, a pseudo-random 14-bit positive integer is generated.
If *node* or *clock_seq* exceed their expected bit count,
only their least significant bits are kept.
.. function:: uuid3(namespace, name)
Generate a UUID based on the MD5 hash of a namespace identifier (which is a
UUID) and a name (which is a :class:`bytes` object or a string
that will be encoded using UTF-8).
that will be encoded using UTF-8)
according to :rfc:`RFC 9562, §5.3 <9562#section-5.3>`.
.. function:: uuid4()
Generate a random UUID.
Generate a random UUID in a cryptographically-secure method
according to :rfc:`RFC 9562, §5.4 <9562#section-5.4>`.
.. function:: uuid5(namespace, name)
Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a
UUID) and a name (which is a :class:`bytes` object or a string
that will be encoded using UTF-8).
that will be encoded using UTF-8)
according to :rfc:`RFC 9562, §5.5 <9562#section-5.5>`.
.. function:: uuid6(node=None, clock_seq=None)
Generate a UUID from a sequence number and the current time according to
:rfc:`9562`.
:rfc:`RFC 9562, §5.6 <9562#section-5.6>`.
This is an alternative to :func:`uuid1` to improve database locality.
When *node* is not specified, :func:`getnode` is used to obtain the hardware
address as a 48-bit positive integer. When a sequence number *clock_seq* is
not specified, a pseudo-random 14-bit positive integer is generated.
If *node* or *clock_seq* exceed their expected bit count, only their least
significant bits are kept.
If *node* or *clock_seq* exceed their expected bit count,
only their least significant bits are kept.
.. versionadded:: 3.14
@ -257,6 +266,10 @@ The :mod:`uuid` module defines the following functions:
non-specified arguments are substituted for a pseudo-random integer of
appropriate size.
By default, *a*, *b* and *c* are not generated by a cryptographically
secure pseudo-random number generator (CSPRNG). Use :func:`uuid4` when
a UUID needs to be used in a security-sensitive context.
.. versionadded:: 3.14

70
Doc/library/venv.rst
View file

@ -105,36 +105,52 @@ The command, if run with ``-h``, will show the available options::
Creates virtual Python environments in one or more target directories.
positional arguments:
ENV_DIR A directory to create the environment in.
options:
-h, --help show this help message and exit
--system-site-packages
Give the virtual environment access to the system
site-packages dir.
--symlinks Try to use symlinks rather than copies, when
symlinks are not the default for the platform.
--copies Try to use copies rather than symlinks, even when
symlinks are the default for the platform.
--clear Delete the contents of the environment directory
if it already exists, before environment creation.
--upgrade Upgrade the environment directory to use this
version of Python, assuming Python has been
upgraded in-place.
--without-pip Skips installing or upgrading pip in the virtual
environment (pip is bootstrapped by default)
--prompt PROMPT Provides an alternative prompt prefix for this
environment.
--upgrade-deps Upgrade core dependencies (pip) to the latest
version in PyPI
--without-scm-ignore-files
Skips adding SCM ignore files to the environment
directory (Git is supported by default).
Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.
.. _venv-cli:
.. program:: venv
.. option:: ENV_DIR
A required argument specifying the directory to create the environment in.
.. option:: --system-site-packages
Give the virtual environment access to the system site-packages directory.
.. option:: --symlinks
Try to use symlinks rather than copies, when symlinks are not the default for the platform.
.. option:: --copies
Try to use copies rather than symlinks, even when symlinks are the default for the platform.
.. option:: --clear
Delete the contents of the environment directory if it already exists, before environment creation.
.. option:: --upgrade
Upgrade the environment directory to use this version of Python, assuming Python has been upgraded in-place.
.. option:: --without-pip
Skips installing or upgrading pip in the virtual environment (pip is bootstrapped by default).
.. option:: --prompt <PROMPT>
Provides an alternative prompt prefix for this environment.
.. option:: --upgrade-deps
Upgrade core dependencies (pip) to the latest version in PyPI.
.. option:: --without-scm-ignore-files
Skips adding SCM ignore files to the environment directory (Git is supported by default).
.. versionchanged:: 3.4
Installs pip by default, added the ``--without-pip`` and ``--copies``

4
Doc/library/zoneinfo.rst
View file

@ -195,7 +195,7 @@ The ``ZoneInfo`` class
The ``ZoneInfo`` class has two alternate constructors:
.. classmethod:: ZoneInfo.from_file(fobj, /, key=None)
.. classmethod:: ZoneInfo.from_file(file_obj, /, key=None)
Constructs a ``ZoneInfo`` object from a file-like object returning bytes
(e.g. a file opened in binary mode or an :class:`io.BytesIO` object).
@ -325,7 +325,7 @@ The behavior of a ``ZoneInfo`` file depends on how it was constructed:
>>> a is b
False
3. ``ZoneInfo.from_file(fobj, /, key=None)``: When constructed from a file, the
3. ``ZoneInfo.from_file(file_obj, /, key=None)``: When constructed from a file, the
``ZoneInfo`` object raises an exception on pickling. If an end user wants to
pickle a ``ZoneInfo`` constructed from a file, it is recommended that they
use a wrapper type or a custom serialization function: either serializing by

2
Doc/reference/datamodel.rst
View file

@ -262,6 +262,8 @@ Booleans (:class:`bool`)
a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
.. _datamodel-float:
:class:`numbers.Real` (:class:`float`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

16
Doc/reference/expressions.rst
View file

@ -134,8 +134,7 @@ Literals
Python supports string and bytes literals and various numeric literals:
.. productionlist:: python-grammar
literal: `stringliteral` | `bytesliteral`
: | `integer` | `floatnumber` | `imagnumber`
literal: `stringliteral` | `bytesliteral` | `NUMBER`
Evaluation of a literal yields an object of the given type (string, bytes,
integer, floating-point number, complex number) with the given value. The value
@ -406,8 +405,9 @@ brackets or curly braces.
Variables used in the generator expression are evaluated lazily when the
:meth:`~generator.__next__` method is called for the generator object (in the same
fashion as normal generators). However, the iterable expression in the
leftmost :keyword:`!for` clause is immediately evaluated, so that an error
produced by it will be emitted at the point where the generator expression
leftmost :keyword:`!for` clause is immediately evaluated, and the
:term:`iterator` is immediately created for that iterable, so that an error
produced while creating the iterator will be emitted at the point where the generator expression
is defined, rather than at the point where the first value is retrieved.
Subsequent :keyword:`!for` clauses and any filter condition in the leftmost
:keyword:`!for` clause cannot be evaluated in the enclosing scope as they may
@ -625,8 +625,10 @@ is already executing raises a :exc:`ValueError` exception.
.. method:: generator.close()
Raises a :exc:`GeneratorExit` at the point where the generator function was
paused. If the generator function catches the exception and returns a
Raises a :exc:`GeneratorExit` exception at the point where the generator
function was paused (equivalent to calling ``throw(GeneratorExit)``).
The exception is raised by the yield expression where the generator was paused.
If the generator function catches the exception and returns a
value, this value is returned from :meth:`close`. If the generator function
is already closed, or raises :exc:`GeneratorExit` (by not catching the
exception), :meth:`close` returns :const:`None`. If the generator yields a
@ -1023,7 +1025,7 @@ series of :term:`arguments <argument>`:
: ["," `keywords_arguments`]
: | `starred_and_keywords` ["," `keywords_arguments`]
: | `keywords_arguments`
positional_arguments: positional_item ("," positional_item)*
positional_arguments: `positional_item` ("," `positional_item`)*
positional_item: `assignment_expression` | "*" `expression`
starred_and_keywords: ("*" `expression` | `keyword_item`)
: ("," "*" `expression` | "," `keyword_item`)*

18
Doc/reference/grammar.rst
View file

@ -8,15 +8,15 @@ used to generate the CPython parser (see :source:`Grammar/python.gram`).
The version here omits details related to code generation and
error recovery.
The notation is a mixture of `EBNF
<https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form>`_
and `PEG <https://en.wikipedia.org/wiki/Parsing_expression_grammar>`_.
In particular, ``&`` followed by a symbol, token or parenthesized
group indicates a positive lookahead (i.e., is required to match but
not consumed), while ``!`` indicates a negative lookahead (i.e., is
required *not* to match). We use the ``|`` separator to mean PEG's
"ordered choice" (written as ``/`` in traditional PEG grammars). See
:pep:`617` for more details on the grammar's syntax.
The notation used here is the same as in the preceding docs,
and is described in the :ref:`notation <notation>` section,
except for a few extra complications:
* ``&e``: a positive lookahead (that is, ``e`` is required to match but
not consumed)
* ``!e``: a negative lookahead (that is, ``e`` is required *not* to match)
* ``~`` ("cut"): commit to the current alternative and fail the rule
even if this fails to parse
.. literalinclude:: ../../Grammar/python.gram
:language: peg

146
Doc/reference/introduction.rst
View file

@ -90,44 +90,122 @@ Notation
.. index:: BNF, grammar, syntax, notation
The descriptions of lexical analysis and syntax use a modified
`Backus–Naur form (BNF) <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ grammar
notation. This uses the following style of definition:
The descriptions of lexical analysis and syntax use a grammar notation that
is a mixture of
`EBNF <https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form>`_
and `PEG <https://en.wikipedia.org/wiki/Parsing_expression_grammar>`_.
For example:
.. productionlist:: notation
name: `lc_letter` (`lc_letter` | "_")*
lc_letter: "a"..."z"
.. grammar-snippet::
:group: notation
The first line says that a ``name`` is an ``lc_letter`` followed by a sequence
of zero or more ``lc_letter``\ s and underscores. An ``lc_letter`` in turn is
any of the single characters ``'a'`` through ``'z'``. (This rule is actually
adhered to for the names defined in lexical and grammar rules in this document.)
name: `letter` (`letter` | `digit` | "_")*
letter: "a"..."z" | "A"..."Z"
digit: "0"..."9"
Each rule begins with a name (which is the name defined by the rule) and
``::=``. A vertical bar (``|``) is used to separate alternatives; it is the
least binding operator in this notation. A star (``*``) means zero or more
repetitions of the preceding item; likewise, a plus (``+``) means one or more
repetitions, and a phrase enclosed in square brackets (``[ ]``) means zero or
one occurrences (in other words, the enclosed phrase is optional). The ``*``
and ``+`` operators bind as tightly as possible; parentheses are used for
grouping. Literal strings are enclosed in quotes. White space is only
meaningful to separate tokens. Rules are normally contained on a single line;
rules with many alternatives may be formatted alternatively with each line after
the first beginning with a vertical bar.
In this example, the first line says that a ``name`` is a ``letter`` followed
by a sequence of zero or more ``letter``\ s, ``digit``\ s, and underscores.
A ``letter`` in turn is any of the single characters ``'a'`` through
``'z'`` and ``A`` through ``Z``; a ``digit`` is a single character from ``0``
to ``9``.
.. index:: lexical definitions, ASCII
Each rule begins with a name (which identifies the rule that's being defined)
followed by a colon, ``:``.
The definition to the right of the colon uses the following syntax elements:
In lexical definitions (as the example above), two more conventions are used:
Two literal characters separated by three dots mean a choice of any single
character in the given (inclusive) range of ASCII characters. A phrase between
angular brackets (``<...>``) gives an informal description of the symbol
defined; e.g., this could be used to describe the notion of 'control character'
if needed.
* ``name``: A name refers to another rule.
Where possible, it is a link to the rule's definition.
Even though the notation used is almost the same, there is a big difference
between the meaning of lexical and syntactic definitions: a lexical definition
operates on the individual characters of the input source, while a syntax
definition operates on the stream of tokens generated by the lexical analysis.
All uses of BNF in the next chapter ("Lexical Analysis") are lexical
definitions; uses in subsequent chapters are syntactic definitions.
* ``TOKEN``: An uppercase name refers to a :term:`token`.
For the purposes of grammar definitions, tokens are the same as rules.
* ``"text"``, ``'text'``: Text in single or double quotes must match literally
(without the quotes). The type of quote is chosen according to the meaning
of ``text``:
* ``'if'``: A name in single quotes denotes a :ref:`keyword <keywords>`.
* ``"case"``: A name in double quotes denotes a
:ref:`soft-keyword <soft-keywords>`.
* ``'@'``: A non-letter symbol in single quotes denotes an
:py:data:`~token.OP` token, that is, a :ref:`delimiter <delimiters>` or
:ref:`operator <operators>`.
* ``e1 e2``: Items separated only by whitespace denote a sequence.
Here, ``e1`` must be followed by ``e2``.
* ``e1 | e2``: A vertical bar is used to separate alternatives.
It denotes PEG's "ordered choice": if ``e1`` matches, ``e2`` is
not considered.
In traditional PEG grammars, this is written as a slash, ``/``, rather than
a vertical bar.
See :pep:`617` for more background and details.
* ``e*``: A star means zero or more repetitions of the preceding item.
* ``e+``: Likewise, a plus means one or more repetitions.
* ``[e]``: A phrase enclosed in square brackets means zero or
one occurrences. In other words, the enclosed phrase is optional.
* ``e?``: A question mark has exactly the same meaning as square brackets:
the preceding item is optional.
* ``(e)``: Parentheses are used for grouping.
* ``"a"..."z"``: Two literal characters separated by three dots mean a choice
of any single character in the given (inclusive) range of ASCII characters.
This notation is only used in
:ref:`lexical definitions <notation-lexical-vs-syntactic>`.
* ``<...>``: A phrase between angular brackets gives an informal description
of the matched symbol (for example, ``<any ASCII character except "\">``),
or an abbreviation that is defined in nearby text (for example, ``<Lu>``).
This notation is only used in
:ref:`lexical definitions <notation-lexical-vs-syntactic>`.
The unary operators (``*``, ``+``, ``?``) bind as tightly as possible;
the vertical bar (``|``) binds most loosely.
White space is only meaningful to separate tokens.
Rules are normally contained on a single line, but rules that are too long
may be wrapped:
.. grammar-snippet::
:group: notation
literal: stringliteral | bytesliteral
| integer | floatnumber | imagnumber
Alternatively, rules may be formatted with the first line ending at the colon,
and each alternative beginning with a vertical bar on a new line.
For example:
.. grammar-snippet::
:group: notation-alt
literal:
| stringliteral
| bytesliteral
| integer
| floatnumber
| imagnumber
This does *not* mean that there is an empty first alternative.
.. index:: lexical definitions
.. _notation-lexical-vs-syntactic:
Lexical and Syntactic definitions
---------------------------------
There is some difference between *lexical* and *syntactic* analysis:
the :term:`lexical analyzer` operates on the individual characters of the
input source, while the *parser* (syntactic analyzer) operates on the stream
of :term:`tokens <token>` generated by the lexical analysis.
However, in some cases the exact boundary between the two phases is a
CPython implementation detail.
The practical difference between the two is that in *lexical* definitions,
all whitespace is significant.
The lexical analyzer :ref:`discards <whitespace>` all whitespace that is not
converted to tokens like :data:`token.INDENT` or :data:`~token.NEWLINE`.
*Syntactic* definitions then use these tokens, rather than source characters.
This documentation uses the same BNF grammar for both styles of definitions.
All uses of BNF in the next chapter (:ref:`lexical`) are lexical definitions;
uses in subsequent chapters are syntactic definitions.

224
Doc/reference/lexical_analysis.rst
View file

@ -922,11 +922,20 @@ Numeric literals
floating-point literal, hexadecimal literal
octal literal, binary literal, decimal literal, imaginary literal, complex literal
There are three types of numeric literals: integers, floating-point numbers, and
imaginary numbers. There are no complex literals (complex numbers can be formed
by adding a real number and an imaginary number).
:data:`~token.NUMBER` tokens represent numeric literals, of which there are
three types: integers, floating-point numbers, and imaginary numbers.
Note that numeric literals do not include a sign; a phrase like ``-1`` is
.. grammar-snippet::
:group: python-grammar
NUMBER: `integer` | `floatnumber` | `imagnumber`
The numeric value of a numeric literal is the same as if it were passed as a
string to the :class:`int`, :class:`float` or :class:`complex` class
constructor, respectively.
Note that not all valid inputs for those constructors are also valid literals.
Numeric literals do not include a sign; a phrase like ``-1`` is
actually an expression composed of the unary operator '``-``' and the literal
``1``.
@ -940,38 +949,67 @@ actually an expression composed of the unary operator '``-``' and the literal
.. _integers:
Integer literals
----------------
^^^^^^^^^^^^^^^^
Integer literals are described by the following lexical definitions:
Integer literals denote whole numbers. For example::
.. productionlist:: python-grammar
integer: `decinteger` | `bininteger` | `octinteger` | `hexinteger`
decinteger: `nonzerodigit` (["_"] `digit`)* | "0"+ (["_"] "0")*
bininteger: "0" ("b" | "B") (["_"] `bindigit`)+
octinteger: "0" ("o" | "O") (["_"] `octdigit`)+
hexinteger: "0" ("x" | "X") (["_"] `hexdigit`)+
nonzerodigit: "1"..."9"
digit: "0"..."9"
bindigit: "0" | "1"
octdigit: "0"..."7"
hexdigit: `digit` | "a"..."f" | "A"..."F"
7
3
2147483647
There is no limit for the length of integer literals apart from what can be
stored in available memory.
stored in available memory::
Underscores are ignored for determining the numeric value of the literal. They
can be used to group digits for enhanced readability. One underscore can occur
between digits, and after base specifiers like ``0x``.
7922816251426433759354395033679228162514264337593543950336
Note that leading zeros in a non-zero decimal number are not allowed. This is
for disambiguation with C-style octal literals, which Python used before version
3.0.
Underscores can be used to group digits for enhanced readability,
and are ignored for determining the numeric value of the literal.
For example, the following literals are equivalent::
Some examples of integer literals::
100_000_000_000
100000000000
1_00_00_00_00_000
7 2147483647 0o177 0b100110111
3 79228162514264337593543950336 0o377 0xdeadbeef
100_000_000_000 0b_1110_0101
Underscores can only occur between digits.
For example, ``_123``, ``321_``, and ``123__321`` are *not* valid literals.
Integers can be specified in binary (base 2), octal (base 8), or hexadecimal
(base 16) using the prefixes ``0b``, ``0o`` and ``0x``, respectively.
Hexadecimal digits 10 through 15 are represented by letters ``A``-``F``,
case-insensitive. For example::
0b100110111
0b_1110_0101
0o177
0o377
0xdeadbeef
0xDead_Beef
An underscore can follow the base specifier.
For example, ``0x_1f`` is a valid literal, but ``0_x1f`` and ``0x__1f`` are
not.
Leading zeros in a non-zero decimal number are not allowed.
For example, ``0123`` is not a valid literal.
This is for disambiguation with C-style octal literals, which Python used
before version 3.0.
Formally, integer literals are described by the following lexical definitions:
.. grammar-snippet::
:group: python-grammar
integer: `decinteger` | `bininteger` | `octinteger` | `hexinteger` | `zerointeger`
decinteger: `nonzerodigit` (["_"] `digit`)*
bininteger: "0" ("b" | "B") (["_"] `bindigit`)+
octinteger: "0" ("o" | "O") (["_"] `octdigit`)+
hexinteger: "0" ("x" | "X") (["_"] `hexdigit`)+
zerointeger: "0"+ (["_"] "0")*
nonzerodigit: "1"..."9"
digit: "0"..."9"
bindigit: "0" | "1"
octdigit: "0"..."7"
hexdigit: `digit` | "a"..."f" | "A"..."F"
.. versionchanged:: 3.6
Underscores are now allowed for grouping purposes in literals.
@ -984,26 +1022,58 @@ Some examples of integer literals::
.. _floating:
Floating-point literals
-----------------------
^^^^^^^^^^^^^^^^^^^^^^^
Floating-point literals are described by the following lexical definitions:
Floating-point (float) literals, such as ``3.14`` or ``1.5``, denote
:ref:`approximations of real numbers <datamodel-float>`.
.. productionlist:: python-grammar
floatnumber: `pointfloat` | `exponentfloat`
pointfloat: [`digitpart`] `fraction` | `digitpart` "."
exponentfloat: (`digitpart` | `pointfloat`) `exponent`
They consist of *integer* and *fraction* parts, each composed of decimal digits.
The parts are separated by a decimal point, ``.``::
2.71828
4.0
Unlike in integer literals, leading zeros are allowed in the numeric parts.
For example, ``077.010`` is legal, and denotes the same number as ``77.10``.
As in integer literals, single underscores may occur between digits to help
readability::
96_485.332_123
3.14_15_93
Either of these parts, but not both, can be empty. For example::
10. # (equivalent to 10.0)
.001 # (equivalent to 0.001)
Optionally, the integer and fraction may be followed by an *exponent*:
the letter ``e`` or ``E``, followed by an optional sign, ``+`` or ``-``,
and a number in the same format as the integer and fraction parts.
The ``e`` or ``E`` represents "times ten raised to the power of"::
1.0e3 # (represents 1.0×10³, or 1000.0)
1.166e-5 # (represents 1.166×10⁻⁵, or 0.00001166)
6.02214076e+23 # (represents 6.02214076×10²³, or 602214076000000000000000.)
In floats with only integer and exponent parts, the decimal point may be
omitted::
1e3 # (equivalent to 1.e3 and 1.0e3)
0e0 # (equivalent to 0.)
Formally, floating-point literals are described by the following
lexical definitions:
.. grammar-snippet::
:group: python-grammar
floatnumber:
| `digitpart` "." [`digitpart`] [`exponent`]
| "." `digitpart` [`exponent`]
| `digitpart` `exponent`
digitpart: `digit` (["_"] `digit`)*
fraction: "." `digitpart`
exponent: ("e" | "E") ["+" | "-"] `digitpart`
Note that the integer and exponent parts are always interpreted using radix 10.
For example, ``077e010`` is legal, and denotes the same number as ``77e10``. The
allowed range of floating-point literals is implementation-dependent. As in
integer literals, underscores are supported for digit grouping.
Some examples of floating-point literals::
3.14 10. .001 1e100 3.14e-10 0e0 3.14_15_93
exponent: ("e" | "E") ["+" | "-"] `digitpart`
.. versionchanged:: 3.6
Underscores are now allowed for grouping purposes in literals.
@ -1014,21 +1084,63 @@ Some examples of floating-point literals::
.. _imaginary:
Imaginary literals
------------------
^^^^^^^^^^^^^^^^^^
Imaginary literals are described by the following lexical definitions:
Python has :ref:`complex number <typesnumeric>` objects, but no complex
literals.
Instead, *imaginary literals* denote complex numbers with a zero
real part.
For example, in math, the complex number 3+4.2\ *i* is written
as the real number 3 added to the imaginary number 4.2\ *i*.
Python uses a similar syntax, except the imaginary unit is written as ``j``
rather than *i*::
3+4.2j
This is an expression composed
of the :ref:`integer literal <integers>` ``3``,
the :ref:`operator <operators>` '``+``',
and the :ref:`imaginary literal <imaginary>` ``4.2j``.
Since these are three separate tokens, whitespace is allowed between them::
3 + 4.2j
No whitespace is allowed *within* each token.
In particular, the ``j`` suffix, may not be separated from the number
before it.
The number before the ``j`` has the same syntax as a floating-point literal.
Thus, the following are valid imaginary literals::
4.2j
3.14j
10.j
.001j
1e100j
3.14e-10j
3.14_15_93j
Unlike in a floating-point literal the decimal point can be omitted if the
imaginary number only has an integer part.
The number is still evaluated as a floating-point number, not an integer::
10j
0j
1000000000000000000000000j # equivalent to 1e+24j
The ``j`` suffix is case-insensitive.
That means you can use ``J`` instead::
3.14J # equivalent to 3.14j
Formally, imaginary literals are described by the following lexical definition:
.. grammar-snippet::
:group: python-grammar
.. productionlist:: python-grammar
imagnumber: (`floatnumber` | `digitpart`) ("j" | "J")
An imaginary literal yields a complex number with a real part of 0.0. Complex
numbers are represented as a pair of floating-point numbers and have the same
restrictions on their range. To create a complex number with a nonzero real
part, add a floating-point number to it, e.g., ``(3+4j)``. Some examples of
imaginary literals::
3.14j 10.j 10j .001j 1e100j 3.14e-10j 3.14_15_93j
.. _operators:

7
Doc/tutorial/introduction.rst
View file

@ -13,10 +13,9 @@ end a multi-line command.
.. only:: html
You can toggle the display of prompts and output by clicking on ``>>>``
in the upper-right corner of an example box. If you hide the prompts
and output for an example, then you can easily copy and paste the input
lines into your interpreter.
You can use the "Copy" button (it appears in the upper-right corner
when hovering over or tapping a code example), which strips prompts
and omits output, to copy and paste the input lines into your interpreter.
.. index:: single: # (hash); comment

6
Doc/tutorial/modules.rst
View file

@ -27,14 +27,16 @@ called :file:`fibo.py` in the current directory with the following contents::
# Fibonacci numbers module
def fib(n): # write Fibonacci series up to n
def fib(n):
"""Write Fibonacci series up to n."""
a, b = 0, 1
while a < n:
print(a, end=' ')
a, b = b, a+b
print()
def fib2(n): # return Fibonacci series up to n
def fib2(n):
"""Return Fibonacci series up to n."""
result = []
a, b = 0, 1
while a < n:

21
Doc/using/cmdline.rst
View file

@ -653,7 +653,7 @@ Miscellaneous options
.. versionadded:: 3.13
* :samp:`-X thread_inherit_context={0,1}` causes :class:`~threading.Thread`
to, by default, use a copy of context of of the caller of
to, by default, use a copy of context of the caller of
``Thread.start()`` when starting. Otherwise, threads will start
with an empty context. If unset, the value of this option defaults
to ``1`` on free-threaded builds and to ``0`` otherwise. See also
@ -669,6 +669,13 @@ Miscellaneous options
.. versionadded:: 3.14
* :samp:`-X tlbc={0,1}` enables (1, the default) or disables (0) thread-local
bytecode in builds configured with :option:`--disable-gil`. When disabled,
this also disables the specializing interpreter. See also
:envvar:`PYTHON_TLBC`.
.. versionadded:: 3.14
It also allows passing arbitrary values and retrieving them through the
:data:`sys._xoptions` dictionary.
@ -1277,7 +1284,7 @@ conflict.
.. envvar:: PYTHON_THREAD_INHERIT_CONTEXT
If this variable is set to ``1`` then :class:`~threading.Thread` will,
by default, use a copy of context of of the caller of ``Thread.start()``
by default, use a copy of context of the caller of ``Thread.start()``
when starting. Otherwise, new threads will start with an empty context.
If unset, this variable defaults to ``1`` on free-threaded builds and to
``0`` otherwise. See also :option:`-X thread_inherit_context<-X>`.
@ -1302,6 +1309,16 @@ conflict.
.. versionadded:: 3.13
.. envvar:: PYTHON_TLBC
If set to ``1`` enables thread-local bytecode. If set to ``0`` thread-local
bytecode and the specializing interpreter are disabled. Only applies to
builds configured with :option:`--disable-gil`.
See also the :option:`-X tlbc <-X>` command-line option.
.. versionadded:: 3.14
Debug-mode variables
~~~~~~~~~~~~~~~~~~~~

12
Doc/using/configure.rst
View file

@ -290,8 +290,8 @@ General Options
.. option:: --disable-gil
Enables **experimental** support for running Python without the
:term:`global interpreter lock` (GIL): free threading build.
Enables support for running Python without the :term:`global interpreter
lock` (GIL): free threading build.
Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to
:data:`sys.abiflags`.
@ -445,6 +445,14 @@ Options for third-party dependencies
C compiler and linker flags for ``libuuid``, used by :mod:`uuid` module,
overriding ``pkg-config``.
.. option:: LIBZSTD_CFLAGS
.. option:: LIBZSTD_LIBS
C compiler and linker flags for ``libzstd``, used by :mod:`compression.zstd` module,
overriding ``pkg-config``.
.. versionadded:: 3.14
.. option:: PANEL_CFLAGS
.. option:: PANEL_LIBS

11
Doc/using/ios.rst
View file

@ -298,9 +298,9 @@ To add Python to an iOS Xcode project:
* Signal handlers (:c:member:`PyConfig.install_signal_handlers`) are *enabled*;
* System logging (:c:member:`PyConfig.use_system_logger`) is *enabled*
(optional, but strongly recommended; this is enabled by default);
* ``PYTHONHOME`` for the interpreter is configured to point at the
* :envvar:`PYTHONHOME` for the interpreter is configured to point at the
``python`` subfolder of your app's bundle; and
* The ``PYTHONPATH`` for the interpreter includes:
* The :envvar:`PYTHONPATH` for the interpreter includes:
- the ``python/lib/python3.X`` subfolder of your app's bundle,
- the ``python/lib/python3.X/lib-dynload`` subfolder of your app's bundle, and
@ -324,7 +324,12 @@ modules in your app, some additional steps will be required:
the ``lib-dynload`` folder can be copied and adapted for this purpose.
* If you're using a separate folder for third-party packages, ensure that folder
is included as part of the ``PYTHONPATH`` configuration in step 10.
is included as part of the :envvar:`PYTHONPATH` configuration in step 10.
* If any of the folders that contain third-party packages will contain ``.pth``
files, you should add that folder as a *site directory* (using
:meth:`site.addsitedir`), rather than adding to :envvar:`PYTHONPATH` or
:attr:`sys.path` directly.
Testing a Python package
------------------------

113
Doc/using/mac.rst
View file

@ -20,13 +20,6 @@ the Pythons provided by the CPython release team for download from
the `python.org website <https://www.python.org/downloads/>`_. See
:ref:`alternative_bundles` for some other options.
.. |usemac_x_dot_y| replace:: 3.13
.. |usemac_python_x_dot_y_literal| replace:: ``python3.13``
.. |usemac_python_x_dot_y_t_literal| replace:: ``python3.13t``
.. |usemac_python_x_dot_y_t_literal_config| replace:: ``python3.13t-config``
.. |usemac_applications_folder_name| replace:: ``Python 3.13``
.. |usemac_applications_folder_version| replace:: ``/Applications/Python 3.13/``
.. _getting-osx:
.. _getting-and-installing-macpython:
@ -64,7 +57,7 @@ Clicking on the **Continue** button brings up the **Read Me** for this installer
Besides other important information, the **Read Me** documents which Python version is
going to be installed and on what versions of macOS it is supported. You may need
to scroll through to read the whole file. By default, this **Read Me** will also be
installed in |usemac_applications_folder_version| and available to read anytime.
installed in |applications_python_version_literal| and available to read anytime.
.. image:: mac_installer_02_readme.png
@ -83,7 +76,7 @@ display. For most uses, the standard set of installation operations is appropria
By pressing the **Customize** button, you can choose to omit or select certain package
components of the installer. Click on each package name to see a description of
what it installs.
To also install support for the optional experimental free-threaded feature,
To also install support for the optional free-threaded feature,
see :ref:`install-freethreaded-macos`.
.. image:: mac_installer_05_custom_install.png
@ -97,7 +90,7 @@ When the installation is complete, the **Summary** window will appear.
.. image:: mac_installer_06_summary.png
Double-click on the :command:`Install Certificates.command`
icon or file in the |usemac_applications_folder_version| window to complete the
icon or file in the |applications_python_version_literal| window to complete the
installation.
.. image:: mac_installer_07_applications.png
@ -114,7 +107,7 @@ Close this terminal window and the installer window.
A default install will include:
* A |usemac_applications_folder_name| folder in your :file:`Applications` folder. In here
* A |python_version_literal| folder in your :file:`Applications` folder. In here
you find :program:`IDLE`, the development environment that is a standard part of official
Python distributions; and :program:`Python Launcher`, which handles double-clicking Python
scripts from the macOS `Finder <https://support.apple.com/en-us/HT201732>`_.
@ -141,7 +134,7 @@ How to run a Python script
There are two ways to invoke the Python interpreter.
If you are familiar with using a Unix shell in a terminal
window, you can invoke |usemac_python_x_dot_y_literal| or ``python3`` optionally
window, you can invoke |python_x_dot_y_literal| or ``python3`` optionally
followed by one or more command line options (described in :ref:`using-on-general`).
The Python tutorial also has a useful section on
:ref:`using Python interactively from a shell <tut-interac>`.
@ -160,7 +153,7 @@ for more information.
To run a Python script file from the terminal window, you can
invoke the interpreter with the name of the script file:
|usemac_python_x_dot_y_literal| ``myscript.py``
|python_x_dot_y_literal| ``myscript.py``
To run your script from the Finder, you can either:
@ -259,20 +252,20 @@ Advanced Topics
Installing Free-threaded Binaries
---------------------------------
.. versionadded:: 3.13 (Experimental)
.. note::
Everything described in this section is considered experimental,
and should be expected to change in future releases.
.. versionadded:: 3.13
The ``python.org`` :ref:`Python for macOS <getting-and-installing-macpython>`
installer package can optionally install an additional build of
Python |usemac_x_dot_y| that supports :pep:`703`, the experimental free-threading feature
Python |version| that supports :pep:`703`, the free-threading feature
(running with the :term:`global interpreter lock` disabled).
Check the release page on ``python.org`` for possible updated information.
Because this feature is still considered experimental, the support for it
The free-threaded mode is working and continues to be improved, but
there is some additional overhead in single-threaded workloads compared
to the regular build. Additionally, third-party packages, in particular ones
with an :term:`extension module`, may not be ready for use in a
free-threaded build, and will re-enable the :term:`GIL`.
Therefore, the support for free-threading
is not installed by default. It is packaged as a separate install option,
available by clicking the **Customize** button on the **Installation Type**
step of the installer as described above.
@ -282,46 +275,54 @@ step of the installer as described above.
If the box next to the **Free-threaded Python** package name is checked,
a separate :file:`PythonT.framework` will also be installed
alongside the normal :file:`Python.framework` in :file:`/Library/Frameworks`.
This configuration allows a free-threaded Python |usemac_x_dot_y| build to co-exist
on your system with a traditional (GIL only) Python |usemac_x_dot_y| build with
minimal risk while installing or testing. This installation layout is itself
experimental and is subject to change in future releases.
This configuration allows a free-threaded Python |version| build to co-exist
on your system with a traditional (GIL only) Python |version| build with
minimal risk while installing or testing. This installation layout may
change in future releases.
Known cautions and limitations:
- The **UNIX command-line tools** package, which is selected by default,
will install links in :file:`/usr/local/bin` for |usemac_python_x_dot_y_t_literal|,
the free-threaded interpreter, and |usemac_python_x_dot_y_t_literal_config|,
will install links in :file:`/usr/local/bin` for |python_x_dot_y_t_literal|,
the free-threaded interpreter, and |python_x_dot_y_t_literal_config|,
a configuration utility which may be useful for package builders.
Since :file:`/usr/local/bin` is typically included in your shell ``PATH``,
in most cases no changes to your ``PATH`` environment variables should
be needed to use |usemac_python_x_dot_y_t_literal|.
be needed to use |python_x_dot_y_t_literal|.
- For this release, the **Shell profile updater** package and the
:file:`Update Shell Profile.command` in |usemac_applications_folder_version|
:file:`Update Shell Profile.command` in |applications_python_version_literal|
do not support the free-threaded package.
- The free-threaded build and the traditional build have separate search
paths and separate :file:`site-packages` directories so, by default,
if you need a package available in both builds, it may need to be installed in both.
The free-threaded package will install a separate instance of :program:`pip` for use
with |usemac_python_x_dot_y_t_literal|.
with |python_x_dot_y_t_literal|.
- To install a package using :command:`pip` without a :command:`venv`:
|usemac_python_x_dot_y_t_literal| ``-m pip install <package_name>``
.. parsed-literal::
python\ |version|\ t -m pip install <package_name>
- When working with multiple Python environments, it is usually safest and easiest
to :ref:`create and use virtual environments <tut-venv>`.
This can avoid possible command name conflicts and confusion about which Python is in use:
|usemac_python_x_dot_y_t_literal| ``-m venv <venv_name>``
.. parsed-literal::
python\ |version|\ t -m venv <venv_name>
then :command:`activate`.
- To run a free-threaded version of IDLE:
|usemac_python_x_dot_y_t_literal| ``-m idlelib``
.. parsed-literal::
python\ |version|\ t -m idlelib
- The interpreters in both builds respond to the same
:ref:`PYTHON environment variables <using-on-envvars>`
@ -337,28 +338,28 @@ Known cautions and limitations:
thus it only needs to be run once.
- If you cannot depend on the link in ``/usr/local/bin`` pointing to the
``python.org`` free-threaded |usemac_python_x_dot_y_t_literal| (for example, if you want
``python.org`` free-threaded |python_x_dot_y_t_literal| (for example, if you want
to install your own version there or some other distribution does),
you can explicitly set your shell ``PATH`` environment variable to
include the ``PythonT`` framework ``bin`` directory:
.. code-block:: sh
.. parsed-literal::
export PATH="/Library/Frameworks/PythonT.framework/Versions/3.13/bin":"$PATH"
export PATH="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin":"$PATH"
The traditional framework installation by default does something similar,
except for :file:`Python.framework`. Be aware that having both framework ``bin``
directories in ``PATH`` can lead to confusion if there are duplicate names
like ``python3.13`` in both; which one is actually used depends on the order
like |python_x_dot_y_literal| in both; which one is actually used depends on the order
they appear in ``PATH``. The ``which python3.x`` or ``which python3.xt``
commands can show which path is being used. Using virtual environments
can help avoid such ambiguities. Another option might be to create
a shell :command:`alias` to the desired interpreter, like:
.. code-block:: sh
.. parsed-literal::
alias py3.13="/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13"
alias py3.13t="/Library/Frameworks/PythonT.framework/Versions/3.13/bin/python3.13t"
alias py\ |version|\ ="/Library/Frameworks/Python.framework/Versions/\ |version|\ /bin/python\ |version|\ "
alias py\ |version|\ t="/Library/Frameworks/PythonT.framework/Versions/\ |version|\ /bin/python\ |version|\ t"
Installing using the command line
---------------------------------
@ -369,22 +370,22 @@ the macOS command line :command:`installer` utility lets you select non-default
options, too. If you are not familiar with :command:`installer`, it can be
somewhat cryptic (see :command:`man installer` for more information).
As an example, the following shell snippet shows one way to do it,
using the ``3.13.0b2`` release and selecting the free-threaded interpreter
using the |x_dot_y_b2_literal| release and selecting the free-threaded interpreter
option:
.. code-block:: sh
.. parsed-literal::
RELEASE="python-3.13.0b2-macos11.pkg"
RELEASE="python-\ |version|\ 0b2-macos11.pkg"
# download installer pkg
curl -O https://www.python.org/ftp/python/3.13.0/${RELEASE}
curl -O \https://www.python.org/ftp/python/\ |version|\ .0/${RELEASE}
# create installer choicechanges to customize the install:
# enable the PythonTFramework-3.13 package
# enable the PythonTFramework-\ |version|\ package
# while accepting the other defaults (install all other packages)
cat > ./choicechanges.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "\http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
<dict>
@ -393,7 +394,7 @@ option:
<key>choiceAttribute</key>
<string>selected</string>
<key>choiceIdentifier</key>
<string>org.python.Python.PythonTFramework-3.13</string>
<string>org.python.Python.PythonTFramework-\ |version|\ </string>
</dict>
</array>
</plist>
@ -404,19 +405,19 @@ option:
You can then test that both installer builds are now available with something like:
.. code-block:: console
.. parsed-literal::
$ # test that the free-threaded interpreter was installed if the Unix Command Tools package was enabled
$ /usr/local/bin/python3.13t -VV
Python 3.13.0b2 experimental free-threading build (v3.13.0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ /usr/local/bin/python\ |version|\ t -VV
Python \ |version|\ .0b2 free-threading build (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ # and the traditional interpreter
$ /usr/local/bin/python3.13 -VV
Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
$ /usr/local/bin/python\ |version|\ -VV
Python \ |version|\ .0b2 (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
$ # test that they are also available without the prefix if /usr/local/bin is on $PATH
$ python3.13t -VV
Python 3.13.0b2 experimental free-threading build (v3.13.0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ python3.13 -VV
Python 3.13.0b2 (v3.13.0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
$ python\ |version|\ t -VV
Python \ |version|\ .0b2 free-threading build (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:57:31) [Clang 15.0.0 (clang-1500.3.9.4)]
$ python\ |version|\ -VV
Python \ |version|\ .0b2 (v\ |version|\ .0b2:3a83b172af, Jun 5 2024, 12:50:24) [Clang 15.0.0 (clang-1500.3.9.4)]
.. note::

2
Doc/whatsnew/3.13.rst
View file

@ -1996,7 +1996,7 @@ New Deprecations
(Contributed by Alex Waygood in :gh:`105566` and :gh:`105570`.)
* Deprecate the :func:`typing.no_type_check_decorator` decorator function,
to be removed in in Python 3.15.
to be removed in Python 3.15.
After eight years in the :mod:`typing` module,
it has yet to be supported by any major type checker.
(Contributed by Alex Waygood in :gh:`106309`.)

270
Doc/whatsnew/3.14.rst
View file

@ -82,8 +82,10 @@ and improvements in user-friendliness and correctness.
.. PEP-sized items next.
* :ref:`PEP 779: Free-threaded Python is officially supported <whatsnew314-pep779>`
* :ref:`PEP 649 and 749: deferred evaluation of annotations <whatsnew314-pep649>`
* :ref:`PEP 741: Python Configuration C API <whatsnew314-pep741>`
* :ref:`PEP 734: Multiple interpreters in the stdlib <whatsnew314-pep734>`
* :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>`
@ -123,6 +125,127 @@ of Python. See :ref:`below <whatsnew314-refcount>` for details.
New features
============
.. _whatsnew314-pep779:
PEP 779: Free-threaded Python is officially supported
-----------------------------------------------------
The free-threaded build of Python is now supported and no longer experimental.
This is the start of phase II where free-threaded Python is officially supported
but still optional.
We are confident that the project is on the right path, and we appreciate the
continued dedication from everyone working to make free-threading ready for
broader adoption across the Python community.
With these recommendations and the acceptance of this PEP, we as the Python
developer community should broadly advertise that free-threading is a supported
Python build option now and into the future, and that it will not be removed
without a proper deprecation schedule.
Any decision to transition to phase III, with free-threading as the default or
sole build of Python is still undecided, and dependent on many factors both
within CPython itself and the community. This decision is for the future.
.. seealso::
:pep:`779` and its `acceptance
<https://discuss.python.org/t/pep-779-criteria-for-supported-status-for-free-threaded-python/84319/123>`__.
.. _whatsnew314-pep734:
PEP 734: Multiple interpreters in the stdlib
--------------------------------------------
The CPython runtime supports running multiple copies of Python in the
same process simultaneously and has done so for over 20 years.
Each of these separate copies is called an "interpreter".
However, the feature had been available only through the C-API.
That limitation is removed in the 3.14 release,
with the new :mod:`concurrent.interpreters` module.
There are at least two notable reasons why using multiple interpreters
is worth considering:
* they support a new (to Python), human-friendly concurrency model
* true multi-core parallelism
For some use cases, concurrency in software enables efficiency and
can simplify software, at a high level. At the same time, implementing
and maintaining all but the simplest concurrency is often a struggle
for the human brain. That especially applies to plain threads
(for example, :mod:`threading`), where all memory is shared between all threads.
With multiple isolated interpreters, you can take advantage of a class
of concurrency models, like CSP or the actor model, that have found
success in other programming languages, like Smalltalk, Erlang,
Haskell, and Go. Think of multiple interpreters like threads
but with opt-in sharing.
Regarding multi-core parallelism: as of the 3.12 release, interpreters
are now sufficiently isolated from one another to be used in parallel.
(See :pep:`684`.) This unlocks a variety of CPU-intensive use cases
for Python that were limited by the :term:`GIL`.
Using multiple interpreters is similar in many ways to
:mod:`multiprocessing`, in that they both provide isolated logical
"processes" that can run in parallel, with no sharing by default.
However, when using multiple interpreters, an application will use
fewer system resources and will operate more efficiently (since it
stays within the same process). Think of multiple interpreters as
having the isolation of processes with the efficiency of threads.
.. XXX Add an example or two.
.. XXX Link to the not-yet-added HOWTO doc.
While the feature has been around for decades, multiple interpreters
have not been used widely, due to low awareness and the lack of a stdlib
module. Consequently, they currently have several notable limitations,
which will improve significantly now that the feature is finally
going mainstream.
Current limitations:
* starting each interpreter has not been optimized yet
* each interpreter uses more memory than necessary
(we will be working next on extensive internal sharing between
interpreters)
* there aren't many options *yet* for truly sharing objects or other
data between interpreters (other than :type:`memoryview`)
* many extension modules on PyPI are not compatible with multiple
interpreters yet (stdlib extension modules *are* compatible)
* the approach to writing applications that use multiple isolated
interpreters is mostly unfamiliar to Python users, for now
The impact of these limitations will depend on future CPython
improvements, how interpreters are used, and what the community solves
through PyPI packages. Depending on the use case, the limitations may
not have much impact, so try it out!
Furthermore, future CPython releases will reduce or eliminate overhead
and provide utilities that are less appropriate on PyPI. In the
meantime, most of the limitations can also be addressed through
extension modules, meaning PyPI packages can fill any gap for 3.14, and
even back to 3.12 where interpreters were finally properly isolated and
stopped sharing the :term:`GIL`. Likewise, we expect to slowly see
libraries on PyPI for high-level abstractions on top of interpreters.
Regarding extension modules, work is in progress to update some PyPI
projects, as well as tools like Cython, pybind11, nanobind, and PyO3.
The steps for isolating an extension module are found at
:ref:`isolating-extensions-howto`. Isolating a module has a lot of
overlap with what is required to support
:ref:`free-threading <whatsnew314-free-threaded-cpython>`,
so the ongoing work in the community in that area will help accelerate
support for multiple interpreters.
Also added in 3.14: :ref:`concurrent.futures.InterpreterPoolExecutor
<whatsnew314-concurrent-futures-interp-pool>`.
.. seealso::
:pep:`734`.
.. _whatsnew314-pep750:
PEP 750: Template strings
@ -155,7 +278,7 @@ As another example, generating HTML attributes from data:
attributes = {"src": "shrubbery.jpg", "alt": "looks nice"}
template = t"<img {attributes}>"
assert html(template) == '<img src="shrubbery.jpg" alt="looks nice" class="looks-nice">'
assert html(template) == '<img src="shrubbery.jpg" alt="looks nice" />'
Compared to using an f-string, the ``html`` function has access to template attributes
containing the original information: static strings, interpolations, and values
@ -296,7 +419,7 @@ 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`)
Victor Stinner, and Rogdham in :gh:`132983`.)
.. seealso::
:pep:`784`.
@ -631,7 +754,7 @@ Improved error messages
.. _whatsnew314-pep741:
PEP 741: Python Configuration C API
PEP 741: Python configuration C API
-----------------------------------
Add a :ref:`PyInitConfig C API <pyinitconfig_api>` to configure the Python
@ -720,43 +843,58 @@ Executing the new tool on the running process will yield a table like this:
python -m asyncio ps 12345
tid task id task name coroutine chain awaiter name awaiter id
---------------------------------------------------------------------------------------------------------------------------------------
8138752 0x564bd3d0210 Task-1 0x0
8138752 0x564bd3d0410 Sundowning _aexit -> __aexit__ -> main Task-1 0x564bd3d0210
8138752 0x564bd3d0610 TMBTE _aexit -> __aexit__ -> main Task-1 0x564bd3d0210
8138752 0x564bd3d0810 TNDNBTG _aexit -> __aexit__ -> album Sundowning 0x564bd3d0410
8138752 0x564bd3d0a10 Levitate _aexit -> __aexit__ -> album Sundowning 0x564bd3d0410
8138752 0x564bd3e0550 DYWTYLM _aexit -> __aexit__ -> album TMBTE 0x564bd3d0610
8138752 0x564bd3e0710 Aqua Regia _aexit -> __aexit__ -> album TMBTE 0x564bd3d0610
tid task id task name coroutine stack awaiter chain awaiter name awaiter id
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1935500 0x7fc930c18050 Task-1 TaskGroup._aexit -> TaskGroup.__aexit__ -> main 0x0
1935500 0x7fc930c18230 Sundowning TaskGroup._aexit -> TaskGroup.__aexit__ -> album TaskGroup._aexit -> TaskGroup.__aexit__ -> main Task-1 0x7fc930c18050
1935500 0x7fc93173fa50 TMBTE TaskGroup._aexit -> TaskGroup.__aexit__ -> album TaskGroup._aexit -> TaskGroup.__aexit__ -> main Task-1 0x7fc930c18050
1935500 0x7fc93173fdf0 TNDNBTG sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album Sundowning 0x7fc930c18230
1935500 0x7fc930d32510 Levitate sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album Sundowning 0x7fc930c18230
1935500 0x7fc930d32890 DYWTYLM sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album TMBTE 0x7fc93173fa50
1935500 0x7fc93161ec30 Aqua Regia sleep -> play TaskGroup._aexit -> TaskGroup.__aexit__ -> album TMBTE 0x7fc93173fa50
or:
or a tree like this:
.. code-block:: bash
python -m asyncio pstree 12345
└── (T) Task-1
└── main
└── __aexit__
└── _aexit
└── main example.py:13
└── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
└── TaskGroup._aexit Lib/asyncio/taskgroups.py:121
├── (T) Sundowning
│ └── album
│ └── __aexit__
│ └── _aexit
│ └── album example.py:8
│ └── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
│ └── TaskGroup._aexit Lib/asyncio/taskgroups.py:121
│ ├── (T) TNDNBTG
│ │ └── play example.py:4
│ │ └── sleep Lib/asyncio/tasks.py:702
│ └── (T) Levitate
│ └── play example.py:4
│ └── sleep Lib/asyncio/tasks.py:702
└── (T) TMBTE
└── album
└── __aexit__
└── _aexit
└── album example.py:8
└── TaskGroup.__aexit__ Lib/asyncio/taskgroups.py:72
└── TaskGroup._aexit Lib/asyncio/taskgroups.py:121
├── (T) DYWTYLM
│ └── play example.py:4
│ └── sleep Lib/asyncio/tasks.py:702
└── (T) Aqua Regia
└── play example.py:4
└── sleep Lib/asyncio/tasks.py:702
If a cycle is detected in the async await graph (which could indicate a
programming issue), the tool raises an error and lists the cycle paths that
prevent tree construction.
prevent tree construction:
.. code-block:: bash
python -m asyncio pstree 12345
ERROR: await-graph contains cycles - cannot print a tree!
cycle: Task-2 → Task-3 → Task-2
(Contributed by Pablo Galindo, Łukasz Langa, Yury Selivanov, and Marta
Gomez Macias in :gh:`91048`.)
@ -840,6 +978,23 @@ be specified by the build backend, as it will no longer be determined
automatically by the C compiler. For a running interpreter, the setting that
was used at compile time can be found using :func:`sysconfig.get_config_var`.
A new flag has been added, :data:`~sys.flags.context_aware_warnings`. This
flag defaults to true for the free-threaded build and false for the GIL-enabled
build. If the flag is true then the :class:`warnings.catch_warnings` context
manager uses a context variable for warning filters. This makes the context
manager behave predicably when used with multiple threads or asynchronous
tasks.
A new flag has been added, :data:`~sys.flags.thread_inherit_context`. This flag
defaults to true for the free-threaded build and false for the GIL-enabled
build. If the flag is true then threads created with :class:`threading.Thread`
start with a copy of the :class:`~contextvars.Context()` of the caller of
:meth:`~threading.Thread.start`. Most significantly, this makes the warning
filtering context established by :class:`~warnings.catch_warnings` be
"inherited" by threads (or asyncio tasks) started within that context. It also
affects other modules that use context variables, such as the :mod:`decimal`
context manager.
.. _whatsnew314-pyrepl-highlighting:
@ -890,6 +1045,18 @@ Please report any bugs or major performance regressions that you encounter!
.. seealso:: :pep:`744`
Concurrent safe warnings control
--------------------------------
The :class:`warnings.catch_warnings` context manager will now optionally
use a context variable for warning filters. This is enabled by setting
the :data:`~sys.flags.context_aware_warnings` flag, either with the ``-X``
command-line option or an environment variable. This gives predicable
warnings control when using :class:`~warnings.catch_warnings` combined with
multiple threads or asynchronous tasks. The flag defaults to true for the
free-threaded build and false for the GIL-enabled build.
(Contributed by Neil Schemenauer and Kumar Aditya in :gh:`130010`.)
Other language changes
======================
@ -1109,6 +1276,8 @@ calendar
concurrent.futures
------------------
.. _whatsnew314-concurrent-futures-interp-pool:
* Add :class:`~concurrent.futures.InterpreterPoolExecutor`,
which exposes "subinterpreters" (multiple Python interpreters in the
same process) to Python code. This is separate from the proposed API
@ -1146,6 +1315,14 @@ concurrent.futures
buffer.
(Contributed by Enzo Bonnal and Josh Rosenberg in :gh:`74028`.)
configparser
------------
* Security fix: will no longer write config files it cannot read. Attempting
to :meth:`configparser.ConfigParser.write` keys containing delimiters or
beginning with the section header pattern will raise a
:class:`configparser.InvalidWriteError`.
(Contributed by Jacob Lincoln in :gh:`129270`.)
contextvars
-----------
@ -1609,6 +1786,16 @@ os
(Contributed by Cody Maloney in :gh:`129205`.)
os.path
-------
* The *strict* parameter to :func:`os.path.realpath` accepts a new value,
:data:`os.path.ALLOW_MISSING`.
If used, errors other than :exc:`FileNotFoundError` will be re-raised;
the resulting path can be missing but it will be free of symlinks.
(Contributed by Petr Viktorin for :cve:`2025-4517`.)
pathlib
-------
@ -1797,6 +1984,28 @@ sysconfig
(Contributed by Xuehai Pan in :gh:`131799`.)
tarfile
-------
* :func:`~tarfile.data_filter` now normalizes symbolic link targets in order to
avoid path traversal attacks.
(Contributed by Petr Viktorin in :gh:`127987` and :cve:`2025-4138`.)
* :func:`~tarfile.TarFile.extractall` now skips fixing up directory attributes
when a directory was removed or replaced by another kind of file.
(Contributed by Petr Viktorin in :gh:`127987` and :cve:`2024-12718`.)
* :func:`~tarfile.TarFile.extract` and :func:`~tarfile.TarFile.extractall`
now (re-)apply the extraction filter when substituting a link (hard or
symbolic) with a copy of another archive member, and when fixing up
directory attributes.
The former raises a new exception, :exc:`~tarfile.LinkFallbackError`.
(Contributed by Petr Viktorin for :cve:`2025-4330` and :cve:`2024-12718`.)
* :func:`~tarfile.TarFile.extract` and :func:`~tarfile.TarFile.extractall`
no longer extract rejected members when
:func:`~tarfile.TarFile.errorlevel` is zero.
(Contributed by Matt Prodani and Petr Viktorin in :gh:`112887`
and :cve:`2025-4435`.)
threading
---------
@ -2431,7 +2640,9 @@ pty
sqlite3
-------
* Remove :data:`!version` and :data:`!version_info` from :mod:`sqlite3`.
* Remove :data:`!version` and :data:`!version_info` from :mod:`sqlite3`;
use :data:`~sqlite3.sqlite_version` and :data:`~sqlite3.sqlite_version_info`
for the actual version number of the runtime SQLite library.
(Contributed by Hugo van Kemenade in :gh:`118924`.)
* Disallow using a sequence of parameters with named placeholders.
@ -2552,6 +2763,7 @@ New features
* :c:func:`PyUnicodeWriter_Discard`
* :c:func:`PyUnicodeWriter_Finish`
* :c:func:`PyUnicodeWriter_Format`
* :c:func:`PyUnicodeWriter_WriteASCII`
* :c:func:`PyUnicodeWriter_WriteChar`
* :c:func:`PyUnicodeWriter_WriteRepr`
* :c:func:`PyUnicodeWriter_WriteStr`
@ -2634,8 +2846,8 @@ New features
* Add :c:func:`PyType_GetBaseByToken` and :c:data:`Py_tp_token` slot for easier
superclass identification, which attempts to resolve the `type checking issue
<https://peps.python.org/pep-0630/#type-checking>`__ mentioned in :pep:`630`
(:gh:`124153`).
<https://peps.python.org/pep-0630/#type-checking>`__ mentioned in :pep:`630`.
(Contributed in :gh:`124153`.)
* Add :c:func:`PyUnicode_Equal` function to the limited C API:
test if two strings are equal.
@ -2828,7 +3040,7 @@ Deprecated
:c:func:`PyUnicodeWriter_WriteSubstring(writer, str, start, end) <PyUnicodeWriter_WriteSubstring>`.
* :c:func:`!_PyUnicodeWriter_WriteASCIIString`:
replace ``_PyUnicodeWriter_WriteASCIIString(&writer, str)`` with
:c:func:`PyUnicodeWriter_WriteUTF8(writer, str) <PyUnicodeWriter_WriteUTF8>`.
:c:func:`PyUnicodeWriter_WriteASCII(writer, str) <PyUnicodeWriter_WriteASCII>`.
* :c:func:`!_PyUnicodeWriter_WriteLatin1String`:
replace ``_PyUnicodeWriter_WriteLatin1String(&writer, str)`` with
:c:func:`PyUnicodeWriter_WriteUTF8(writer, str) <PyUnicodeWriter_WriteUTF8>`.

44
Doc/whatsnew/3.15.rst
View file

@ -115,6 +115,9 @@ math
* Add :func:`math.isnormal` and :func:`math.issubnormal` functions.
(Contributed by Sergey B Kirpichev in :gh:`132908`.)
* Add :func:`math.signbit` function.
(Contributed by Bénédikt Tran in :gh:`135853`.)
os.path
-------
@ -136,6 +139,20 @@ shelve
(Contributed by Andrea Oliveri in :gh:`134004`.)
sqlite3
-------
* The :ref:`command-line interface <sqlite3-cli>` has several new features:
* SQL keyword completion on <tab>.
(Contributed by Long Tan in :gh:`133393`.)
* Prompts, error messages, and help text are now colored.
This is enabled by default, see :ref:`using-on-controlling-color` for
details.
(Contributed by Stan Ulbrych and Łukasz Langa in :gh:`133461`)
ssl
---
@ -237,6 +254,13 @@ platform
(Contributed by Alexey Makridenko in :gh:`133604`.)
sre_*
-----
* Removed :mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules.
(Contributed by Stan Ulbrych in :gh:`135994`.)
sysconfig
---------
@ -288,6 +312,11 @@ that may require changes to your code.
Build changes
=============
* Removed implicit fallback to the bundled copy of the ``libmpdec`` library.
Now this should be explicitly enabled with :option:`--with-system-libmpdec`
set to ``no`` or with :option:`!--without-system-libmpdec`.
(Contributed by Sergey B Kirpichev in :gh:`115119`.)
C API changes
=============
@ -300,11 +329,9 @@ New features
functions as replacements for :c:func:`PySys_GetObject`.
(Contributed by Serhiy Storchaka in :gh:`108512`.)
* Add :c:func:`PyUnicodeWriter_WriteASCII` function to write an ASCII string
into a :c:type:`PyUnicodeWriter`. The function is faster than
:c:func:`PyUnicodeWriter_WriteUTF8`, but has an undefined behavior if the
input string contains non-ASCII characters.
(Contributed by Victor Stinner in :gh:`133968`.)
* Add :c:type:`PyUnstable_Unicode_GET_CACHED_HASH` to get the cached hash of
a string. See the documentation for caveats.
(Contributed by Petr Viktorin in :gh:`131510`)
Porting to Python 3.15
@ -321,6 +348,13 @@ Porting to Python 3.15
(Contributed by Serhiy Storchaka in :gh:`133595`.)
* Private functions promoted to public C APIs:
* ``PyMutex_IsLocked()`` : :c:func:`PyMutex_IsLocked`
The |pythoncapi_compat_project| can be used to get most of these new
functions on Python 3.14 and older.
Deprecated C APIs
-----------------

3
Grammar/python.gram
View file

@ -184,8 +184,9 @@ return_stmt[stmt_ty]:
| 'return' a=[star_expressions] { _PyAST_Return(a, EXTRA) }
raise_stmt[stmt_ty]:
| 'raise' a=expression 'from' b=expression { _PyAST_Raise(a, b, EXTRA) }
| invalid_raise_stmt
| 'raise' a=expression b=['from' z=expression { z }] { _PyAST_Raise(a, b, EXTRA) }
| 'raise' a=expression { _PyAST_Raise(a, NULL, EXTRA) }
| 'raise' { _PyAST_Raise(NULL, NULL, EXTRA) }
pass_stmt[stmt_ty]:

13
Include/Python.h
View file

@ -59,14 +59,6 @@
# include <intrin.h> // __readgsqword()
#endif
// Suppress known warnings in Python header files.
#if defined(_MSC_VER)
// Warning that alignas behaviour has changed. Doesn't affect us, because we
// never relied on the old behaviour.
#pragma warning(push)
#pragma warning(disable: 5274)
#endif
// Include Python header files
#include "pyport.h"
#include "pymacro.h"
@ -146,9 +138,4 @@
#include "cpython/pyfpe.h"
#include "cpython/tracemalloc.h"
// Restore warning filter
#ifdef _MSC_VER
#pragma warning(pop)
#endif
#endif /* !Py_PYTHON_H */

10
Include/audit.h
View file

@ -1,5 +1,5 @@
#ifndef Py_AUDIT_H
#define Py_AUDIT_H
#ifndef _Py_AUDIT_H
#define _Py_AUDIT_H
#ifdef __cplusplus
extern "C" {
#endif
@ -18,13 +18,13 @@ PyAPI_FUNC(int) PySys_AuditTuple(
#ifndef Py_LIMITED_API
# define Py_CPYTHON_AUDIT_H
# define _Py_CPYTHON_AUDIT_H
# include "cpython/audit.h"
# undef Py_CPYTHON_AUDIT_H
# undef _Py_CPYTHON_AUDIT_H
#endif
#ifdef __cplusplus
}
#endif
#endif /* !Py_AUDIT_H */
#endif /* !_Py_AUDIT_H */

7
Include/ceval.h
View file

@ -133,13 +133,6 @@ PyAPI_FUNC(void) PyEval_ReleaseThread(PyThreadState *tstate);
#define FVS_MASK 0x4
#define FVS_HAVE_SPEC 0x4
/* Special methods used by LOAD_SPECIAL */
#define SPECIAL___ENTER__ 0
#define SPECIAL___EXIT__ 1
#define SPECIAL___AENTER__ 2
#define SPECIAL___AEXIT__ 3
#define SPECIAL_MAX 3
#ifndef Py_LIMITED_API
# define Py_CPYTHON_CEVAL_H
# include "cpython/ceval.h"

2
Include/cpython/audit.h
View file

@ -1,4 +1,4 @@
#ifndef Py_CPYTHON_AUDIT_H
#ifndef _Py_CPYTHON_AUDIT_H
# error "this header file must not be included directly"
#endif

5
Include/cpython/funcobject.h
View file

@ -97,11 +97,6 @@ static inline PyObject* PyFunction_GET_GLOBALS(PyObject *func) {
}
#define PyFunction_GET_GLOBALS(func) PyFunction_GET_GLOBALS(_PyObject_CAST(func))
static inline PyObject* PyFunction_GET_BUILTINS(PyObject *func) {
return _PyFunction_CAST(func)->func_builtins;
}
#define PyFunction_GET_BUILTINS(func) PyFunction_GET_BUILTINS(_PyObject_CAST(func))
static inline PyObject* PyFunction_GET_MODULE(PyObject *func) {
return _PyFunction_CAST(func)->func_module;
}

11
Include/cpython/lock.h
View file

@ -36,6 +36,9 @@ PyAPI_FUNC(void) PyMutex_Lock(PyMutex *m);
// exported function for unlocking the mutex
PyAPI_FUNC(void) PyMutex_Unlock(PyMutex *m);
// exported function for checking if the mutex is locked
PyAPI_FUNC(int) PyMutex_IsLocked(PyMutex *m);
// Locks the mutex.
//
// If the mutex is currently locked, the calling thread will be parked until
@ -61,3 +64,11 @@ _PyMutex_Unlock(PyMutex *m)
}
}
#define PyMutex_Unlock _PyMutex_Unlock
// Checks if the mutex is currently locked.
static inline int
_PyMutex_IsLocked(PyMutex *m)
{
return (_Py_atomic_load_uint8(&m->_bits) & _Py_LOCKED) != 0;
}
#define PyMutex_IsLocked _PyMutex_IsLocked

6
Include/cpython/pystate.h
View file

@ -28,10 +28,10 @@ typedef int (*Py_tracefunc)(PyObject *, PyFrameObject *, int, PyObject *);
#define PyTrace_OPCODE 7
/* Remote debugger support */
#define MAX_SCRIPT_PATH_SIZE 512
typedef struct _remote_debugger_support {
#define Py_MAX_SCRIPT_PATH_SIZE 512
typedef struct {
int32_t debugger_pending_call;
char debugger_script_path[MAX_SCRIPT_PATH_SIZE];
char debugger_script_path[Py_MAX_SCRIPT_PATH_SIZE];
} _PyRemoteDebuggerSupport;
typedef struct _err_stackitem {

131
Include/cpython/unicodeobject.h
View file

@ -47,6 +47,63 @@ static inline Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch) {
/* --- Unicode Type ------------------------------------------------------- */
struct _PyUnicodeObject_state {
/* If interned is non-zero, the two references from the
dictionary to this object are *not* counted in ob_refcnt.
The possible values here are:
0: Not Interned
1: Interned
2: Interned and Immortal
3: Interned, Immortal, and Static
This categorization allows the runtime to determine the right
cleanup mechanism at runtime shutdown. */
#ifdef Py_GIL_DISABLED
// Needs to be accessed atomically, so can't be a bit field.
unsigned char interned;
#else
unsigned int interned:2;
#endif
/* Character size:
- PyUnicode_1BYTE_KIND (1):
* character type = Py_UCS1 (8 bits, unsigned)
* all characters are in the range U+0000-U+00FF (latin1)
* if ascii is set, all characters are in the range U+0000-U+007F
(ASCII), otherwise at least one character is in the range
U+0080-U+00FF
- PyUnicode_2BYTE_KIND (2):
* character type = Py_UCS2 (16 bits, unsigned)
* all characters are in the range U+0000-U+FFFF (BMP)
* at least one character is in the range U+0100-U+FFFF
- PyUnicode_4BYTE_KIND (4):
* character type = Py_UCS4 (32 bits, unsigned)
* all characters are in the range U+0000-U+10FFFF
* at least one character is in the range U+10000-U+10FFFF
*/
unsigned int kind:3;
/* Compact is with respect to the allocation scheme. Compact unicode
objects only require one memory block while non-compact objects use
one block for the PyUnicodeObject struct and another for its data
buffer. */
unsigned int compact:1;
/* The string only contains characters in the range U+0000-U+007F (ASCII)
and the kind is PyUnicode_1BYTE_KIND. If ascii is set and compact is
set, use the PyASCIIObject structure. */
unsigned int ascii:1;
/* The object is statically allocated. */
unsigned int statically_allocated:1;
#ifndef Py_GIL_DISABLED
/* Historical: padding to ensure that PyUnicode_DATA() is always aligned to
4 bytes (see issue gh-63736 on m68k) */
unsigned int :24;
#endif
};
/* ASCII-only strings created through PyUnicode_New use the PyASCIIObject
structure. state.ascii and state.compact are set, and the data
immediately follow the structure. utf8_length can be found
@ -99,67 +156,8 @@ typedef struct {
PyObject_HEAD
Py_ssize_t length; /* Number of code points in the string */
Py_hash_t hash; /* Hash value; -1 if not set */
#ifdef Py_GIL_DISABLED
/* Ensure 4 byte alignment for PyUnicode_DATA(), see gh-63736 on m68k.
In the non-free-threaded build, we'll use explicit padding instead */
_Py_ALIGN_AS(4)
#endif
struct {
/* If interned is non-zero, the two references from the
dictionary to this object are *not* counted in ob_refcnt.
The possible values here are:
0: Not Interned
1: Interned
2: Interned and Immortal
3: Interned, Immortal, and Static
This categorization allows the runtime to determine the right
cleanup mechanism at runtime shutdown. */
#ifdef Py_GIL_DISABLED
// Needs to be accessed atomically, so can't be a bit field.
unsigned char interned;
#else
unsigned int interned:2;
#endif
/* Character size:
- PyUnicode_1BYTE_KIND (1):
* character type = Py_UCS1 (8 bits, unsigned)
* all characters are in the range U+0000-U+00FF (latin1)
* if ascii is set, all characters are in the range U+0000-U+007F
(ASCII), otherwise at least one character is in the range
U+0080-U+00FF
- PyUnicode_2BYTE_KIND (2):
* character type = Py_UCS2 (16 bits, unsigned)
* all characters are in the range U+0000-U+FFFF (BMP)
* at least one character is in the range U+0100-U+FFFF
- PyUnicode_4BYTE_KIND (4):
* character type = Py_UCS4 (32 bits, unsigned)
* all characters are in the range U+0000-U+10FFFF
* at least one character is in the range U+10000-U+10FFFF
*/
unsigned int kind:3;
/* Compact is with respect to the allocation scheme. Compact unicode
objects only require one memory block while non-compact objects use
one block for the PyUnicodeObject struct and another for its data
buffer. */
unsigned int compact:1;
/* The string only contains characters in the range U+0000-U+007F (ASCII)
and the kind is PyUnicode_1BYTE_KIND. If ascii is set and compact is
set, use the PyASCIIObject structure. */
unsigned int ascii:1;
/* The object is statically allocated. */
unsigned int statically_allocated:1;
#ifndef Py_GIL_DISABLED
/* Padding to ensure that PyUnicode_DATA() is always aligned to
4 bytes (see issue gh-63736 on m68k) */
unsigned int :24;
#endif
} state;
/* Ensure 4 byte alignment for PyUnicode_DATA(), see gh-63736 on m68k. */
_Py_ALIGNED_DEF(4, struct _PyUnicodeObject_state) state;
} PyASCIIObject;
/* Non-ASCII strings allocated through PyUnicode_New use the
@ -300,6 +298,17 @@ static inline Py_ssize_t PyUnicode_GET_LENGTH(PyObject *op) {
}
#define PyUnicode_GET_LENGTH(op) PyUnicode_GET_LENGTH(_PyObject_CAST(op))
/* Returns the cached hash, or -1 if not cached yet. */
static inline Py_hash_t
PyUnstable_Unicode_GET_CACHED_HASH(PyObject *op) {
assert(PyUnicode_Check(op));
#ifdef Py_GIL_DISABLED
return _Py_atomic_load_ssize_relaxed(&_PyASCIIObject_CAST(op)->hash);
#else
return _PyASCIIObject_CAST(op)->hash;
#endif
}
/* Write into the canonical representation, this function does not do any sanity
checks and is intended for usage in loops. The caller should cache the
kind and data pointers obtained from other function calls.

2
Include/internal/mimalloc/mimalloc/types.h
View file

@ -705,7 +705,7 @@ void _mi_stat_counter_increase(mi_stat_counter_t* stat, size_t amount);
// Thread Local data
// ------------------------------------------------------
// A "span" is is an available range of slices. The span queues keep
// A "span" is an available range of slices. The span queues keep
// track of slice spans of at most the given `slice_count` (but more than the previous size class).
typedef struct mi_span_queue_s {
mi_slice_t* first;

17
Include/internal/pycore_ceval.h
View file

@ -239,6 +239,16 @@ static inline void _Py_LeaveRecursiveCall(void) {
extern _PyInterpreterFrame* _PyEval_GetFrame(void);
extern PyObject * _PyEval_GetGlobalsFromRunningMain(PyThreadState *);
extern int _PyEval_EnsureBuiltins(
PyThreadState *,
PyObject *,
PyObject **p_builtins);
extern int _PyEval_EnsureBuiltinsWithModule(
PyThreadState *,
PyObject *,
PyObject **p_builtins);
PyAPI_FUNC(PyObject *)_Py_MakeCoro(PyFunctionObject *func);
/* Handle signals, pending calls, GIL drop request
@ -356,6 +366,13 @@ extern int _PyRunRemoteDebugger(PyThreadState *tstate);
PyAPI_FUNC(_PyStackRef)
_PyForIter_VirtualIteratorNext(PyThreadState* tstate, struct _PyInterpreterFrame* frame, _PyStackRef iter, _PyStackRef *index_ptr);
/* Special methods used by LOAD_SPECIAL */
#define SPECIAL___ENTER__ 0
#define SPECIAL___EXIT__ 1
#define SPECIAL___AENTER__ 2
#define SPECIAL___AEXIT__ 3
#define SPECIAL_MAX 3
#ifdef __cplusplus
}
#endif

24
Include/internal/pycore_critical_section.h
View file

@ -64,7 +64,7 @@ extern "C" {
# define _Py_CRITICAL_SECTION_ASSERT_OBJECT_LOCKED(op) \
if (Py_REFCNT(op) != 1) { \
_Py_CRITICAL_SECTION_ASSERT_MUTEX_LOCKED(&_PyObject_CAST(op)->ob_mutex); \
_PyCriticalSection_AssertHeldObj(_PyObject_CAST(op)); \
}
#else /* Py_DEBUG */
@ -239,6 +239,28 @@ _PyCriticalSection_AssertHeld(PyMutex *mutex)
#endif
}
static inline void
_PyCriticalSection_AssertHeldObj(PyObject *op)
{
#ifdef Py_DEBUG
PyMutex *mutex = &_PyObject_CAST(op)->ob_mutex;
PyThreadState *tstate = _PyThreadState_GET();
uintptr_t prev = tstate->critical_section;
if (prev & _Py_CRITICAL_SECTION_TWO_MUTEXES) {
PyCriticalSection2 *cs = (PyCriticalSection2 *)(prev & ~_Py_CRITICAL_SECTION_MASK);
_PyObject_ASSERT_WITH_MSG(op,
(cs != NULL && (cs->_cs_base._cs_mutex == mutex || cs->_cs_mutex2 == mutex)),
"Critical section of object is not held");
}
else {
PyCriticalSection *cs = (PyCriticalSection *)(prev & ~_Py_CRITICAL_SECTION_MASK);
_PyObject_ASSERT_WITH_MSG(op,
(cs != NULL && cs->_cs_mutex == mutex),
"Critical section of object is not held");
}
#endif
}
#endif /* Py_GIL_DISABLED */
#ifdef __cplusplus

37
Include/internal/pycore_crossinterp.h
View file

@ -303,10 +303,10 @@ typedef struct _excinfo {
const char *errdisplay;
} _PyXI_excinfo;
PyAPI_FUNC(int) _PyXI_InitExcInfo(_PyXI_excinfo *info, PyObject *exc);
PyAPI_FUNC(_PyXI_excinfo *) _PyXI_NewExcInfo(PyObject *exc);
PyAPI_FUNC(void) _PyXI_FreeExcInfo(_PyXI_excinfo *info);
PyAPI_FUNC(PyObject *) _PyXI_FormatExcInfo(_PyXI_excinfo *info);
PyAPI_FUNC(PyObject *) _PyXI_ExcInfoAsObject(_PyXI_excinfo *info);
PyAPI_FUNC(void) _PyXI_ClearExcInfo(_PyXI_excinfo *info);
typedef enum error_code {
@ -322,19 +322,20 @@ typedef enum error_code {
_PyXI_ERR_NOT_SHAREABLE = -9,
} _PyXI_errcode;
typedef struct xi_failure _PyXI_failure;
typedef struct _sharedexception {
// The originating interpreter.
PyInterpreterState *interp;
// The kind of error to propagate.
_PyXI_errcode code;
// The exception information to propagate, if applicable.
// This is populated only for some error codes,
// but always for _PyXI_ERR_UNCAUGHT_EXCEPTION.
_PyXI_excinfo uncaught;
} _PyXI_error;
PyAPI_FUNC(_PyXI_failure *) _PyXI_NewFailure(void);
PyAPI_FUNC(void) _PyXI_FreeFailure(_PyXI_failure *);
PyAPI_FUNC(_PyXI_errcode) _PyXI_GetFailureCode(_PyXI_failure *);
PyAPI_FUNC(int) _PyXI_InitFailure(_PyXI_failure *, _PyXI_errcode, PyObject *);
PyAPI_FUNC(void) _PyXI_InitFailureUTF8(
_PyXI_failure *,
_PyXI_errcode,
const char *);
PyAPI_FUNC(PyObject *) _PyXI_ApplyError(_PyXI_error *err);
PyAPI_FUNC(int) _PyXI_UnwrapNotShareableError(
PyThreadState *,
_PyXI_failure *);
// A cross-interpreter session involves entering an interpreter
@ -366,19 +367,21 @@ PyAPI_FUNC(int) _PyXI_Enter(
_PyXI_session_result *);
PyAPI_FUNC(int) _PyXI_Exit(
_PyXI_session *,
_PyXI_errcode,
_PyXI_failure *,
_PyXI_session_result *);
PyAPI_FUNC(PyObject *) _PyXI_GetMainNamespace(
_PyXI_session *,
_PyXI_errcode *);
_PyXI_failure *);
PyAPI_FUNC(int) _PyXI_Preserve(
_PyXI_session *,
const char *,
PyObject *,
_PyXI_errcode *);
PyAPI_FUNC(PyObject *) _PyXI_GetPreserved(_PyXI_session_result *, const char *);
_PyXI_failure *);
PyAPI_FUNC(PyObject *) _PyXI_GetPreserved(
_PyXI_session_result *,
const char *);
/*************/

2
Include/internal/pycore_debug_offsets.h
View file

@ -368,7 +368,7 @@ typedef struct _Py_DebugOffsets {
.remote_debugging_enabled = offsetof(PyInterpreterState, config.remote_debug), \
.debugger_pending_call = offsetof(_PyRemoteDebuggerSupport, debugger_pending_call), \
.debugger_script_path = offsetof(_PyRemoteDebuggerSupport, debugger_script_path), \
.debugger_script_path_size = MAX_SCRIPT_PATH_SIZE, \
.debugger_script_path_size = Py_MAX_SCRIPT_PATH_SIZE, \
}, \
}

2
Include/internal/pycore_freelist_state.h
View file

@ -16,6 +16,7 @@ extern "C" {
# define Py_dicts_MAXFREELIST 80
# define Py_dictkeys_MAXFREELIST 80
# define Py_floats_MAXFREELIST 100
# define Py_complexes_MAXFREELIST 100
# define Py_ints_MAXFREELIST 100
# define Py_slices_MAXFREELIST 1
# define Py_ranges_MAXFREELIST 6
@ -43,6 +44,7 @@ struct _Py_freelist {
struct _Py_freelists {
struct _Py_freelist floats;
struct _Py_freelist complexes;
struct _Py_freelist ints;
struct _Py_freelist tuples[PyTuple_MAXSAVESIZE];
struct _Py_freelist lists;

5
Include/internal/pycore_function.h
View file

@ -41,6 +41,11 @@ extern PyObject *_Py_set_function_type_params(
PyAPI_FUNC(int)
_PyFunction_VerifyStateless(PyThreadState *, PyObject *);
static inline PyObject* _PyFunction_GET_BUILTINS(PyObject *func) {
return _PyFunction_CAST(func)->func_builtins;
}
#define _PyFunction_GET_BUILTINS(func) _PyFunction_GET_BUILTINS(_PyObject_CAST(func))
#ifdef __cplusplus
}

1
Include/internal/pycore_global_objects_fini_generated.h generated
View file

@ -1136,6 +1136,7 @@ _PyStaticObjects_CheckRefcnt(PyInterpreterState *interp) {
_PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(offset_src));
_PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(on_type_read));
_PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(onceregistry));
_PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(only_active_thread));
_PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(only_keys));
_PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(oparg));
_PyStaticObject_CheckRefcnt((PyObject *)&_Py_ID(opcode));

Some files were not shown because too many files have changed in this diff Show more