What’s New In Python 3.12

Editor:

Adam Turner

This article explains the new features in Python 3.12, compared to 3.11. Python 3.12 was released on October 2, 2023. For full details, see thechangelog.

See also

PEP 693– Python 3.12 Release Schedule

Summary – Release highlights

Python 3.12 is a stable release of the Python programming language, with a mix of changes to the language and the standard library. The library changes focus on cleaning up deprecated APIs, usability, and correctness. Of note, thedistutilspackage has been removed from the standard library. Filesystem support inosandpathlibhas seen a number of improvements, and several modules have better performance.

The language changes focus on usability, asf-stringshave had many limitations removed and ‘Did you mean…’ suggestions continue to improve. The newtype parameter syntax andtypestatement improve ergonomics for usinggeneric typesandtype aliaseswith static type checkers.

This article doesn’t attempt to provide a complete specification of all new features, but instead gives a convenient overview. For full details, you should refer to the documentation, such as theLibrary Reference andLanguage Reference. If you want to understand the complete implementation and design rationale for a change, refer to the PEP for a particular new feature; but note that PEPs usually are not kept up-to-date once a feature has been fully implemented.

New syntax features:

New grammar features:

Interpreter improvements:

Python data model improvements:

Significant improvements in the standard library:

Security improvements:

  • Replace the builtinhashlibimplementations of SHA1, SHA3, SHA2-384, SHA2-512, and MD5 with formally verified code from the HACL*project. These builtin implementations remain as fallbacks that are only used when OpenSSL does not provide them.

C API improvements:

CPython implementation improvements:

  • PEP 709,comprehension inlining

  • CPython supportfor the Linuxperfprofiler

  • Implement stack overflow protection on supported platforms

New typing features:

Important deprecations, removals or restrictions:

  • PEP 623:Removewstrfrom Unicode objects in Python’s C API, reducing the size of everystrobject by at least 8 bytes.

  • PEP 632:Remove thedistutilspackage. Seethe migration guide for advice replacing the APIs it provided. The third-partySetuptools package continues to providedistutils, if you still require it in Python 3.12 and beyond.

  • gh-95299:Do not pre-installsetuptoolsin virtual environments created withvenv. This means thatdistutils,setuptools,pkg_resources, andeasy_installwill no longer available by default; to access these runpipinstallsetuptoolsin theactivated virtual environment.

  • Theasynchat,asyncore,andimpmodules have been removed, along with severalunittest.TestCase method aliases.

New Features

PEP 695: Type Parameter Syntax

Generic classes and functions underPEP 484were declared using a verbose syntax that left the scope of type parameters unclear and required explicit declarations of variance.

PEP 695introduces a new, more compact and explicit way to create generic classesandfunctions:

defmax[T](args:Iterable[T])->T:
...

classlist[T]:
def__getitem__(self,index:int,/)->T:
...

defappend(self,element:T)->None:
...

In addition, the PEP introduces a new way to declaretype aliases using thetypestatement, which creates an instance of TypeAliasType:

typePoint=tuple[float,float]

Type aliases can also begeneric:

typePoint[T]=tuple[T,T]

The new syntax allows declaringTypeVarTuple andParamSpecparameters, as well asTypeVar parameters with bounds or constraints:

typeIntFunc[**P]=Callable[P,int]# ParamSpec
typeLabeledTuple[*Ts]=tuple[str,*Ts]# TypeVarTuple
typeHashableSequence[T:Hashable]=Sequence[T]# TypeVar with bound
typeIntOrStrSequence[T:(int,str)]=Sequence[T]# TypeVar with constraints

The value of type aliases and the bound and constraints of type variables created through this syntax are evaluated only on demand (see lazy evaluation). This means type aliases are able to refer to other types defined later in the file.

Type parameters declared through a type parameter list are visible within the scope of the declaration and any nested scopes, but not in the outer scope. For example, they can be used in the type annotations for the methods of a generic class or in the class body. However, they cannot be used in the module scope after the class is defined. SeeType parameter listsfor a detailed description of the runtime semantics of type parameters.

In order to support these scoping semantics, a new kind of scope is introduced, theannotation scope.Annotation scopes behave for the most part like function scopes, but interact differently with enclosing class scopes. In Python 3.13,annotationswill also be evaluated in annotation scopes.

SeePEP 695for more details.

(PEP written by Eric Traut. Implementation by Jelle Zijlstra, Eric Traut, and others ingh-103764.)

PEP 701: Syntactic formalization of f-strings

PEP 701lifts some restrictions on the usage off-strings. Expression components inside f-strings can now be any valid Python expression, including strings reusing the same quote as the containing f-string, multi-line expressions, comments, backslashes, and unicode escape sequences. Let’s cover these in detail:

  • Quote reuse: in Python 3.11, reusing the same quotes as the enclosing f-string raises aSyntaxError,forcing the user to either use other available quotes (like using double quotes or triple quotes if the f-string uses single quotes). In Python 3.12, you can now do things like this:

    >>>songs=['Take me back to Eden','Alkaline','Ascensionism']
>>>f"This is the playlist:{",".join(songs)}"
'This is the playlist: Take me back to Eden, Alkaline, Ascensionism'

    Note that before this change there was no explicit limit in how f-strings can be nested, but the fact that string quotes cannot be reused inside the expression component of f-strings made it impossible to nest f-strings arbitrarily. In fact, this is the most nested f-string that could be written:

    >>>f"""{f'''{f'{f"{1+1}"}'}'''}"""
'2'

    As now f-strings can contain any valid Python expression inside expression components, it is now possible to nest f-strings arbitrarily:

    >>>f"{f"{f"{f"{f"{f"{1+1}"}"}"}"}"}"
'2'

  • Multi-line expressions and comments: In Python 3.11, f-string expressions must be defined in a single line, even if the expression within the f-string could normally span multiple lines (like literal lists being defined over multiple lines), making them harder to read. In Python 3.12 you can now define f-strings spanning multiple lines, and add inline comments:

    >>> f "This is the playlist: {", ".join([
... 'Take me back to Eden', # My, my, those eyes like fire
... 'Alkaline', # Not acid nor alkaline
... 'Ascensionism' # Take to the broken skies at last
... ])}"
'This is the playlist: Take me back to Eden, Alkaline, Ascensionism'

  • Backslashes and unicode characters: before Python 3.12 f-string expressions couldn’t contain any\character. This also affected unicodeescape sequences(such as\N{snowman}) as these contain the\Npart that previously could not be part of expression components of f-strings. Now, you can define expressions like this:

    >>>print(f"This is the playlist:{"\n".join(songs)}")
This is the playlist: Take me back to Eden
Alkaline
Ascensionism
>>>print(f"This is the playlist:{"\N{BLACK HEART SUIT}".join(songs)}")
This is the playlist: Take me back to Eden♥Alkaline♥Ascensionism

SeePEP 701for more details.

As a positive side-effect of how this feature has been implemented (by parsing f-strings withthe PEG parser), now error messages for f-strings are more precise and include the exact location of the error. For example, in Python 3.11, the following f-string raises aSyntaxError:

>>>my_string=f"{xzy}"+f"{1+1}"
File"<stdin>",line1
(xzy)
^^^
SyntaxError:f-string: invalid syntax. Perhaps you forgot a comma?

but the error message doesn’t include the exact location of the error within the line and also has the expression artificially surrounded by parentheses. In Python 3.12, as f-strings are parsed with the PEG parser, error messages can be more precise and show the entire line:

>>>my_string=f"{xzy}"+f"{1+1}"
File"<stdin>",line1
my_string=f"{xzy}"+f"{1+1}"
^^^
SyntaxError:invalid syntax. Perhaps you forgot a comma?

(Contributed by Pablo Galindo, Batuhan Taskaya, Lysandros Nikolaou, Cristián Maureira-Fredes and Marta Gómez ingh-102856.PEP written by Pablo Galindo, Batuhan Taskaya, Lysandros Nikolaou and Marta Gómez).

PEP 684: A Per-Interpreter GIL

PEP 684introduces a per-interpreterGIL, so that sub-interpreters may now be created with a unique GIL per interpreter. This allows Python programs to take full advantage of multiple CPU cores. This is currently only available through the C-API, though a Python API isanticipated for 3.13.

Use the newPy_NewInterpreterFromConfig()function to create an interpreter with its own GIL:

PyInterpreterConfigconfig={
.check_multi_interp_extensions=1,
.gil=PyInterpreterConfig_OWN_GIL,
};
PyThreadState*tstate=NULL;
PyStatusstatus=Py_NewInterpreterFromConfig(&tstate,&config);
if(PyStatus_Exception(status)){
return-1;
}
/* The new interpreter is now active in the current thread. */

For further examples how to use the C-API for sub-interpreters with a per-interpreter GIL, seeModules/_xxsubinterpretersmodule.c.

(Contributed by Eric Snow ingh-104210,etc.)

PEP 669: Low impact monitoring for CPython

PEP 669defines a newAPIfor profilers, debuggers, and other tools to monitor events in CPython. It covers a wide range of events, including calls, returns, lines, exceptions, jumps, and more. This means that you only pay for what you use, providing support for near-zero overhead debuggers and coverage tools. Seesys.monitoringfor details.

(Contributed by Mark Shannon ingh-103082.)

PEP 688: Making the buffer protocol accessible in Python

PEP 688introduces a way to use thebuffer protocol from Python code. Classes that implement the__buffer__()method are now usable as buffer types.

The newcollections.abc.BufferABC provides a standard way to represent buffer objects, for example in type annotations. The newinspect.BufferFlagsenum represents the flags that can be used to customize buffer creation. (Contributed by Jelle Zijlstra ingh-102500.)

PEP 709: Comprehension inlining

Dictionary, list, and set comprehensions are now inlined, rather than creating a new single-use function object for each execution of the comprehension. This speeds up execution of a comprehension by up to two times. SeePEP 709for further details.

Comprehension iteration variables remain isolated and don’t overwrite a variable of the same name in the outer scope, nor are they visible after the comprehension. Inlining does result in a few visible behavior changes:

  • There is no longer a separate frame for the comprehension in tracebacks, and tracing/profiling no longer shows the comprehension as a function call.

  • Thesymtablemodule will no longer produce child symbol tables for each comprehension; instead, the comprehension’s locals will be included in the parent function’s symbol table.

  • Callinglocals()inside a comprehension now includes variables from outside the comprehension, and no longer includes the synthetic.0 variable for the comprehension “argument”.

  • A comprehension iterating directly overlocals()(e.g.[kforkin locals()]) may see “RuntimeError: dictionary changed size during iteration” when run under tracing (e.g. code coverage measurement). This is the same behavior already seen in e.g.forkinlocals():.To avoid the error, first create a list of keys to iterate over:keys=list(locals());[kforkin keys].

(Contributed by Carl Meyer and Vladimir Matveev inPEP 709.)

Improved Error Messages

  • Modules from the standard library are now potentially suggested as part of the error messages displayed by the interpreter when aNameErroris raised to the top level. (Contributed by Pablo Galindo ingh-98254.)

    >>>sys.version_info
Traceback (most recent call last):
File"<stdin>",line1,in<module>
NameError:name 'sys' is not defined. Did you forget to import 'sys'?

  • Improve the error suggestion forNameErrorexceptions for instances. Now if aNameErroris raised in a method and the instance has an attribute that’s exactly equal to the name in the exception, the suggestion will includeself.<NAME>instead of the closest match in the method scope. (Contributed by Pablo Galindo ingh-99139.)

    >>>classA:
...def__init__(self):
...self.blech=1
...
...deffoo(self):
...somethin=blech
...
>>>A().foo()
Traceback (most recent call last):
File"<stdin>",line1
somethin=blech
^^^^^
NameError:name 'blech' is not defined. Did you mean: 'self.blech'?

  • Improve theSyntaxErrorerror message when the user typesimportx fromyinstead offromyimportx.(Contributed by Pablo Galindo ingh-98931.)

    >>>importa.y.zfromb.y.z
Traceback (most recent call last):
File"<stdin>",line1
importa.y.zfromb.y.z
^^^^^^^^^^^^^^^^^^^^^^^
SyntaxError:Did you mean to use 'from... import...' instead?

  • ImportErrorexceptions raised from failedfrom<module>import <name>statements now include suggestions for the value of<name>based on the available names in<module>.(Contributed by Pablo Galindo ingh-91058.)

    >>>fromcollectionsimportchainmap
Traceback (most recent call last):
File"<stdin>",line1,in<module>
ImportError:cannot import name 'chainmap' from 'collections'. Did you mean: 'ChainMap'?

Other Language Changes

  • The parser now raisesSyntaxErrorwhen parsing source code containing null bytes. (Contributed by Pablo Galindo ingh-96670.)

  • A backslash-character pair that is not a valid escape sequence now generates aSyntaxWarning,instead ofDeprecationWarning. For example,re pile( "\d+\.\d+" )now emits aSyntaxWarning ("\d"is an invalid escape sequence, use raw strings for regular expression:re pile(r "\d+\.\d+" )). In a future Python version,SyntaxErrorwill eventually be raised, instead ofSyntaxWarning. (Contributed by Victor Stinner ingh-98401.)

  • Octal escapes with value larger than0o377(ex:"\477"), deprecated in Python 3.11, now produce aSyntaxWarning,instead of DeprecationWarning. In a future Python version they will be eventually aSyntaxError. (Contributed by Victor Stinner ingh-98401.)

  • Variables used in the target part of comprehensions that are not stored to can now be used in assignment expressions (:=). For example, in[(b:=1)fora,b.propinsome_iter],the assignment to bis now allowed. Note that assigning to variables stored to in the target part of comprehensions (likea) is still disallowed, as perPEP 572. (Contributed by Nikita Sobolev ingh-100581.)

  • Exceptions raised in a class or type’s__set_name__method are no longer wrapped by aRuntimeError.Context information is added to the exception as aPEP 678note. (Contributed by Irit Katriel ingh-77757.)

  • When atry-except*construct handles the entireExceptionGroup and raises one other exception, that exception is no longer wrapped in an ExceptionGroup.Also changed in version 3.11.4. (Contributed by Irit Katriel ingh-103590.)

  • The Garbage Collector now runs only on the eval breaker mechanism of the Python bytecode evaluation loop instead of object allocations. The GC can also run whenPyErr_CheckSignals()is called so C extensions that need to run for a long time without executing any Python code also have a chance to execute the GC periodically. (Contributed by Pablo Galindo in gh-97922.)

  • All builtin and extension callables expecting boolean parameters now accept arguments of any type instead of justboolandint. (Contributed by Serhiy Storchaka ingh-60203.)

  • memoryviewnow supports the half-float type (the “e” format code). (Contributed by Donghee Na and Antoine Pitrou ingh-90751.)

  • sliceobjects are now hashable, allowing them to be used as dict keys and set items. (Contributed by Will Bradshaw, Furkan Onder, and Raymond Hettinger ingh-101264.)

  • sum()now uses Neumaier summation to improve accuracy and commutativity when summing floats or mixed ints and floats. (Contributed by Raymond Hettinger ingh-100425.)

  • ast.parse()now raisesSyntaxErrorinstead ofValueError when parsing source code containing null bytes. (Contributed by Pablo Galindo ingh-96670.)

  • The extraction methods intarfile,andshutil.unpack_archive(), have a new afilterargument that allows limiting tar features than may be surprising or dangerous, such as creating files outside the destination directory. Seetarfile extraction filtersfor details. In Python 3.14, the default will switch to'data'. (Contributed by Petr Viktorin inPEP 706.)

  • types.MappingProxyTypeinstances are now hashable if the underlying mapping is hashable. (Contributed by Serhiy Storchaka ingh-87995.)

  • Addsupport for the perf profilerthrough the new environment variablePYTHONPERFSUPPORT and command-line option-Xperf, as well as the newsys.activate_stack_trampoline(), sys.deactivate_stack_trampoline(), andsys.is_stack_trampoline_active()functions. (Design by Pablo Galindo. Contributed by Pablo Galindo and Christian Heimes with contributions from Gregory P. Smith [Google] and Mark Shannon ingh-96123.)

New Modules

  • None.

Improved Modules

array

asyncio

calendar

csv

dis

  • Pseudo instruction opcodes (which are used by the compiler but do not appear in executable bytecode) are now exposed in the dismodule. HAVE_ARGUMENTis still relevant to real opcodes, but it is not useful for pseudo instructions. Use the new dis.hasargcollection instead. (Contributed by Irit Katriel ingh-94216.)

  • Add thedis.hasexccollection to signify instructions that set an exception handler. (Contributed by Irit Katriel ingh-94216.)

fractions

importlib.resources

inspect

itertools

  • Additertools.batched()for collecting into even-sized tuples where the last batch may be shorter than the rest. (Contributed by Raymond Hettinger ingh-98363.)

math

  • Addmath.sumprod()for computing a sum of products. (Contributed by Raymond Hettinger ingh-100485.)

  • Extendmath.nextafter()to include astepsargument for moving up or down multiple steps at a time. (Contributed by Matthias Goergens, Mark Dickinson, and Raymond Hettinger ingh-94906.)

os

  • Addos.PIDFD_NONBLOCKto open a file descriptor for a process withos.pidfd_open()in non-blocking mode. (Contributed by Kumar Aditya ingh-93312.)

  • os.DirEntrynow includes anos.DirEntry.is_junction() method to check if the entry is a junction. (Contributed by Charles Machalow ingh-99547.)

  • Addos.listdrives(),os.listvolumes()andos.listmounts() functions on Windows for enumerating drives, volumes and mount points. (Contributed by Steve Dower ingh-102519.)

  • os.stat()andos.lstat()are now more accurate on Windows. Thest_birthtimefield will now be filled with the creation time of the file, andst_ctimeis deprecated but still contains the creation time (but in the future will return the last metadata change, for consistency with other platforms).st_devmay be up to 64 bits andst_inoup to 128 bits depending on your file system, and st_rdevis always set to zero rather than incorrect values. Both functions may be significantly faster on newer releases of Windows. (Contributed by Steve Dower ingh-99726.)

os.path

pathlib

pdb

  • Add convenience variables to hold values temporarily for debug session and provide quick access to values like the current frame or the return value. (Contributed by Tian Gao ingh-103693.)

random

shutil

  • shutil.make_archive()now passes theroot_dirargument to custom archivers which support it. In this case it no longer temporarily changes the current working directory of the process toroot_dirto perform archiving. (Contributed by Serhiy Storchaka ingh-74696.)

  • shutil.rmtree()now accepts a new argumentonexcwhich is an error handler likeonerrorbut which expects an exception instance rather than a(typ, val, tb)triplet.onerroris deprecated. (Contributed by Irit Katriel ingh-102828.)

  • shutil.which()now consults thePATHEXTenvironment variable to find matches withinPATHon Windows even when the givencmdincludes a directory component. (Contributed by Charles Machalow ingh-103179.)

    shutil.which()will callNeedCurrentDirectoryForExePathWwhen querying for executables on Windows to determine if the current working directory should be prepended to the search path. (Contributed by Charles Machalow ingh-103179.)

    shutil.which()will return a path matching thecmdwith a component fromPATHEXTprior to a direct match elsewhere in the search path on Windows. (Contributed by Charles Machalow ingh-103179.)

sqlite3

statistics

  • Extendstatistics.correlation()to include as arankedmethod for computing the Spearman correlation of ranked data. (Contributed by Raymond Hettinger ingh-95861.)

sys

tempfile

threading

tkinter

  • tkinter.Canvas.coords()now flattens its arguments. It now accepts not only coordinates as separate arguments (x1,y1,x2,y2,...) and a sequence of coordinates ([x1,y1,x2,y2,...]), but also coordinates grouped in pairs ((x1,y1),(x2,y2),...and[(x1,y1),(x2,y2),...]), likecreate_*()methods. (Contributed by Serhiy Storchaka ingh-94473.)

tokenize

types

typing

  • isinstance()checks against runtime-checkableprotocolsnow use inspect.getattr_static()rather thanhasattr()to lookup whether attributes exist. This means that descriptors and__getattr__() methods are no longer unexpectedly evaluated duringisinstance()checks against runtime-checkable protocols. However, it may also mean that some objects which used to be considered instances of a runtime-checkable protocol may no longer be considered instances of that protocol on Python 3.12+, and vice versa. Most users are unlikely to be affected by this change. (Contributed by Alex Waygood ingh-102433.)

  • The members of a runtime-checkable protocol are now considered “frozen” at runtime as soon as the class has been created. Monkey-patching attributes onto a runtime-checkable protocol will still work, but will have no impact on isinstance()checks comparing objects to the protocol. For example:

    >>>fromtypingimportProtocol,runtime_checkable
>>>@runtime_checkable
...classHasX(Protocol):
...x=1
...
>>>classFoo:...
...
>>>f=Foo()
>>>isinstance(f,HasX)
False
>>>f.x=1
>>>isinstance(f,HasX)
True
>>>HasX.y=2
>>>isinstance(f,HasX)# unchanged, even though HasX now also has a "y" attribute
True

    This change was made in order to speed upisinstance()checks against runtime-checkable protocols.

  • The performance profile ofisinstance()checks against runtime-checkableprotocolshas changed significantly. Mostisinstance()checks against protocols with only a few members should be at least 2x faster than in 3.11, and some may be 20x faster or more. However,isinstance()checks against protocols with many members may be slower than in Python 3.11. (Contributed by Alex Waygood ingh-74690andgh-103193.)

  • Alltyping.TypedDictandtyping.NamedTupleclasses now have the __orig_bases__attribute. (Contributed by Adrian Garcia Badaracco in gh-103699.)

  • Addfrozen_defaultparameter totyping.dataclass_transform(). (Contributed by Erik De Bonte ingh-99957.)

unicodedata

  • The Unicode database has been updated to version 15.0.0. (Contributed by Benjamin Peterson ingh-96734).

unittest

Add a--durationscommand line option, showing the N slowest test cases:

Python 3-munittest--durations=3lib.tests.test_threading
.....
Slowesttestdurations
----------------------------------------------------------------------
1.210stest_timeout(Lib.test.test_threading.BarrierTests)
1.003stest_default_timeout(Lib.test.test_threading.BarrierTests)
0.518stest_timeout(Lib.test.test_threading.EventTests)

(0.000durationshidden.Use-vtoshowthesedurations.)
----------------------------------------------------------------------
Ran158testsin9.869s

OK(skipped=3)

(Contributed by Giampaolo Rodola ingh-48330)

uuid

Optimizations

  • Removewstrandwstr_lengthmembers from Unicode objects. It reduces object size by 8 or 16 bytes on 64bit platform. (PEP 623) (Contributed by Inada Naoki ingh-92536.)

  • Add experimental support for using the BOLT binary optimizer in the build process, which improves performance by 1-5%. (Contributed by Kevin Modzelewski ingh-90536and tuned by Donghee Na ingh-101525)

  • Speed up the regular expression substitution (functionsre.sub()and re.subn()and correspondingre.Patternmethods) for replacement strings containing group references by 2–3 times. (Contributed by Serhiy Storchaka ingh-91524.)

  • Speed upasyncio.Taskcreation by deferring expensive string formatting. (Contributed by Itamar Oren ingh-103793.)

  • Thetokenize.tokenize()andtokenize.generate_tokens()functions are up to 64% faster as a side effect of the changes required to coverPEP 701in thetokenizemodule. (Contributed by Marta Gómez Macías and Pablo Galindo ingh-102856.)

  • Speed upsuper()method calls and attribute loads via the newLOAD_SUPER_ATTRinstruction. (Contributed by Carl Meyer and Vladimir Matveev ingh-103497.)

CPython bytecode changes

Demos and Tools

  • Remove theTools/demo/directory which contained old demo scripts. A copy can be found in theold-demos project. (Contributed by Victor Stinner ingh-97681.)

  • Remove outdated example scripts of theTools/scripts/directory. A copy can be found in theold-demos project. (Contributed by Victor Stinner ingh-97669.)

Deprecated

Pending Removal in Python 3.13

Modules (seePEP 594):

  • aifc

  • audioop

  • cgi

  • cgitb

  • chunk

  • crypt

  • imghdr

  • mailcap

  • msilib

  • nis

  • nntplib

  • ossaudiodev

  • pipes

  • sndhdr

  • spwd

  • sunau

  • telnetlib

  • uu

  • xdrlib

Other modules:

APIs:

Pending Removal in Python 3.14

Pending Removal in Python 3.15

  • The import system:

    • Setting__cached__on a module while failing to set__spec__.cached is deprecated. In Python 3.15,__cached__will cease to be set or take into consideration by the import system or standard library. (gh-97879)

    • Setting__package__on a module while failing to set__spec__.parent is deprecated. In Python 3.15,__package__will cease to be set or take into consideration by the import system or standard library. (gh-97879)

  • ctypes:

    • The undocumentedctypes.SetPointerType()function has been deprecated since Python 3.13.

  • http.server:

    • The obsolete and rarely usedCGIHTTPRequestHandler has been deprecated since Python 3.13. No direct replacement exists. Anythingis better than CGI to interface a web server with a request handler.

    • The--cgiflag to thePython -m http.server command-line interface has been deprecated since Python 3.13.

  • locale:

  • pathlib:

  • platform:

    • java_ver()has been deprecated since Python 3.13. This function is only useful for Jython support, has a confusing API, and is largely untested.

  • threading:

    • RLock()will take no arguments in Python 3.15. Passing any arguments has been deprecated since Python 3.14, as the Python version does not permit any arguments, but the C version allows any number of positional or keyword arguments, ignoring every argument.

  • typing:

    • The undocumented keyword argument syntax for creating NamedTupleclasses (e.g.Point=NamedTuple( "Point",x=int,y=int)) has been deprecated since Python 3.13. Use the class-based syntax or the functional syntax instead.

    • Thetyping.no_type_check_decorator()decorator function has been deprecated since Python 3.13. After eight years in thetypingmodule, it has yet to be supported by any major type checker.

  • wave:

Pending Removal in Python 3.16

  • builtins:

    • Bitwise inversion on boolean types,~Trueor~False has been deprecated since Python 3.12, as it produces surprising and unintuitive results (-2and-1). Usenotxinstead for the logical negation of a Boolean. In the rare case that you need the bitwise inversion of the underlying integer, convert tointexplicitly (~int(x)).

  • array:

    • The'u'format code (wchar_t) has been deprecated in documentation since Python 3.3 and at runtime since Python 3.13. Use the'w'format code (Py_UCS4) for Unicode characters instead.

  • shutil:

    • TheExecErrorexception has been deprecated since Python 3.14. It has not been used by any function inshutilsince Python 3.4, and is now an alias ofRuntimeError.

  • symtable:

  • sys:

  • tarfile:

    • The undocumented and unusedTarFile.tarfileattribute has been deprecated since Python 3.13.

Pending Removal in Future Versions

The following APIs will be removed in the future, although there is currently no date scheduled for their removal.

  • argparse:Nesting argument groups and nesting mutually exclusive groups are deprecated.

  • array’s'u'format code (gh-57281)

  • builtins:

    • bool(NotImplemented).

    • Generators:throw(type,exc,tb)andathrow(type,exc,tb) signature is deprecated: usethrow(exc)andathrow(exc)instead, the single argument signature.

    • Currently Python accepts numeric literals immediately followed by keywords, for example0inx,1orx,0if1else2.It allows confusing and ambiguous expressions like[0x1forxiny](which can be interpreted as [0x1forxiny]or[0x1forxiny]). A syntax warning is raised if the numeric literal is immediately followed by one of keywords and,else,for,if, in,isandor.In a future release it will be changed to a syntax error. (gh-87999)

    • Support for__index__()and__int__()method returning non-int type: these methods will be required to return an instance of a strict subclass of int.

    • Support for__float__()method returning a strict subclass of float:these methods will be required to return an instance of float.

    • Support for__complex__()method returning a strict subclass of complex:these methods will be required to return an instance of complex.

    • Delegation ofint()to__trunc__()method.

    • Passing a complex number as therealorimagargument in the complex()constructor is now deprecated; it should only be passed as a single positional argument. (Contributed by Serhiy Storchaka ingh-109218.)

  • calendar:calendar.Januaryandcalendar.Februaryconstants are deprecated and replaced bycalendar.JANUARYand calendar.FEBRUARY. (Contributed by Prince Roshan ingh-103636.)

  • codeobject.co_lnotab:use thecodeobject.co_lines()method instead.

  • datetime:

    • utcnow(): usedatetime.datetime.now(tz=datetime.UTC).

    • utcfromtimestamp(): usedatetime.datetime.fromtimestamp(timestamp,tz=datetime.UTC).

  • gettext:Plural value must be an integer.

  • importlib:

    • load_module()method: useexec_module()instead.

    • cache_from_source()debug_overrideparameter is deprecated: use theoptimizationparameter instead.

  • importlib.metadata:

    • EntryPointstuple interface.

    • ImplicitNoneon return values.

  • logging:thewarn()method has been deprecated since Python 3.3, usewarning()instead.

  • mailbox:Use of StringIO input and text mode is deprecated, use BytesIO and binary mode instead.

  • os:Callingos.register_at_fork()in multi-threaded process.

  • pydoc.ErrorDuringImport:A tuple value forexc_infoparameter is deprecated, use an exception instance.

  • re:More strict rules are now applied for numerical group references and group names in regular expressions. Only sequence of ASCII digits is now accepted as a numerical reference. The group name in bytes patterns and replacement strings can now only contain ASCII letters and digits and underscore. (Contributed by Serhiy Storchaka ingh-91760.)

  • sre_compile,sre_constantsandsre_parsemodules.

  • shutil:rmtree()’sonerrorparameter is deprecated in Python 3.12; use theonexcparameter instead.

  • ssloptions and protocols:

    • ssl.SSLContextwithout protocol argument is deprecated.

    • ssl.SSLContext:set_npn_protocols()and selected_npn_protocol()are deprecated: use ALPN instead.

    • ssl.OP_NO_SSL*options

    • ssl.OP_NO_TLS*options

    • ssl.PROTOCOL_SSLv3

    • ssl.PROTOCOL_TLS

    • ssl.PROTOCOL_TLSv1

    • ssl.PROTOCOL_TLSv1_1

    • ssl.PROTOCOL_TLSv1_2

    • ssl.TLSVersion.SSLv3

    • ssl.TLSVersion.TLSv1

    • ssl.TLSVersion.TLSv1_1

  • sysconfig.is_ Python _build()check_homeparameter is deprecated and ignored.

  • threadingmethods:

  • typing.Text(gh-92332).

  • unittest.IsolatedAsyncioTestCase:it is deprecated to return a value that is notNonefrom a test case.

  • urllib.parsedeprecated functions:urlparse()instead

    • splitattr()

    • splithost()

    • splitnport()

    • splitpasswd()

    • splitport()

    • splitquery()

    • splittag()

    • splittype()

    • splituser()

    • splitvalue()

    • to_bytes()

  • urllib.request:URLopenerand FancyURLopenerstyle of invoking requests is deprecated. Use newerurlopen()functions and methods.

  • wsgiref:SimpleHandler.stdout.write()should not do partial writes.

  • xml.etree.ElementTree:Testing the truth value of an Elementis deprecated. In a future release it will always returnTrue.Prefer explicitlen(elem)or elemisnotNonetests instead.

  • zipimport.zipimporter.load_module()is deprecated: useexec_module()instead.

Removed

asynchat and asyncore

  • These two modules have been removed according to the schedule inPEP 594, having been deprecated in Python 3.6. Useasyncioinstead. (Contributed by Nikita Sobolev ingh-96580.)

configparser

distutils

  • Remove thedistutilspackage. It was deprecated in Python 3.10 by PEP 632“Deprecate distutils module”. For projects still using distutilsand cannot be updated to something else, thesetuptools project can be installed: it still providesdistutils. (Contributed by Victor Stinner ingh-92584.)

ensurepip

  • Remove the bundled setuptools wheel fromensurepip, and stop installing setuptools in environments created byvenv.

    pip(>=22.1)does not require setuptools to be installed in the environment.setuptools-based (anddistutils-based) packages can still be used withpipinstall,since pip will provide setuptoolsin the build environment it uses for building a package.

    easy_install,pkg_resources,setuptoolsanddistutils are no longer provided by default in environments created with venvor bootstrapped withensurepip,since they are part of thesetuptoolspackage. For projects relying on these at runtime, thesetuptoolsproject should be declared as a dependency and installed separately (typically, using pip).

    (Contributed by Pradyun Gedam ingh-95299.)

enum

  • Removeenum’sEnumMeta.__getattr__,which is no longer needed for enum attribute access. (Contributed by Ethan Furman ingh-95083.)

ftplib

  • Removeftplib’sFTP_TLS.ssl_versionclass attribute: use the contextparameter instead. (Contributed by Victor Stinner ingh-94172.)

gzip

  • Remove thefilenameattribute ofgzip’sgzip.GzipFile, deprecated since Python 2.6, use thenameattribute instead. In write mode, thefilenameattribute added'.gz'file extension if it was not present. (Contributed by Victor Stinner ingh-94196.)

hashlib

  • Remove the pure Python implementation ofhashlib’s hashlib.pbkdf2_hmac(),deprecated in Python 3.10. Python 3.10 and newer requires OpenSSL 1.1.1 (PEP 644): this OpenSSL version provides a C implementation ofpbkdf2_hmac()which is faster. (Contributed by Victor Stinner ingh-94199.)

importlib

  • Many previously deprecated cleanups inimportlibhave now been completed:

    • References to, and support formodule_repr()has been removed. (Contributed by Barry Warsaw ingh-97850.)

    • importlib.util.set_package,importlib.util.set_loaderand importlib.util.module_for_loaderhave all been removed. (Contributed by Brett Cannon and Nikita Sobolev ingh-65961andgh-97850.)

    • Support forfind_loader()andfind_module()APIs have been removed. (Contributed by Barry Warsaw ingh-98040.)

    • importlib.abc.Finder,pkgutil.ImpImporter,andpkgutil.ImpLoader have been removed. (Contributed by Barry Warsaw ingh-98040.)

imp

  • Theimpmodule has been removed. (Contributed by Barry Warsaw in gh-98040.)

    To migrate, consult the following correspondence table:

    imp

    importlib

    imp.NullImporter

    InsertNoneintosys.path_importer_cache

    imp.cache_from_source()

    importlib.util.cache_from_source()

    imp.find_module()

    importlib.util.find_spec()

    imp.get_magic()

    importlib.util.MAGIC_NUMBER

    imp.get_suffixes()

    importlib.machinery.SOURCE_SUFFIXES,importlib.machinery.EXTENSION_SUFFIXES,andimportlib.machinery.BYTECODE_SUFFIXES

    imp.get_tag()

    sys.implementation.cache_tag

    imp.load_module()

    importlib.import_module()

    imp.new_module(name)

    types.ModuleType(name)

    imp.reload()

    importlib.reload()

    imp.source_from_cache()

    importlib.util.source_from_cache()

    imp.load_source()

    See below

    Replaceimp.load_source()with:

    importimportlib.util
importimportlib.machinery

defload_source(modname,filename):
loader=importlib.machinery.SourceFileLoader(modname,filename)
spec=importlib.util.spec_from_file_location(modname,filename,loader=loader)
module=importlib.util.module_from_spec(spec)
# The module is always executed and not cached in sys.modules.
# Uncomment the following line to cache the module.
# sys.modules[module.__name__] = module
loader.exec_module(module)
returnmodule

  • Removeimpfunctions and attributes with no replacements:

    • Undocumented functions:

      • imp.init_builtin()

      • imp.load_compiled()

      • imp.load_dynamic()

      • imp.load_package()

    • imp.lock_held(),imp.acquire_lock(),imp.release_lock(): the locking scheme has changed in Python 3.3 to per-module locks.

    • imp.find_module()constants:SEARCH_ERROR,PY_SOURCE, PY_COMPILED,C_EXTENSION,PY_RESOURCE,PKG_DIRECTORY, C_BUILTIN,PY_FROZEN,PY_CODERESOURCE,IMP_HOOK.

io

  • Removeio’sio.OpenWrapperand_pyio.OpenWrapper,deprecated in Python 3.10: just useopen()instead. Theopen()(io.open()) function is a built-in function. Since Python 3.10,_pyio.open()is also a static method. (Contributed by Victor Stinner ingh-94169.)

locale

smtpd

  • Thesmtpdmodule has been removed according to the schedule inPEP 594, having been deprecated in Python 3.4.7 and 3.5.4. Use theaiosmtpdPyPI module or any other asyncio-based server instead. (Contributed by Oleg Iarygin ingh-93243.)

sqlite3

  • The following undocumentedsqlite3features, deprecated in Python 3.10, are now removed:

    • sqlite3.enable_shared_cache()

    • sqlite3.OptimizedUnicode

    If a shared cache must be used, open the database in URI mode using the cache=sharedquery parameter.

    Thesqlite3.OptimizedUnicodetext factory has been an alias for strsince Python 3.3. Code that previously set the text factory to OptimizedUnicodecan either usestrexplicitly, or rely on the default value which is alsostr.

    (Contributed by Erlend E. Aasland ingh-92548.)

ssl

  • Removessl’sssl.RAND_pseudo_bytes()function, deprecated in Python 3.6: useos.urandom()orssl.RAND_bytes()instead. (Contributed by Victor Stinner ingh-94199.)

  • Remove thessl.match_hostname()function. It was deprecated in Python 3.7. OpenSSL performs hostname matching since Python 3.7, Python no longer uses the ssl.match_hostname()function. (Contributed by Victor Stinner ingh-94199.)

  • Remove thessl.wrap_socket()function, deprecated in Python 3.7: instead, create assl.SSLContextobject and call its ssl.SSLContext.wrap_socketmethod. Any package that still uses ssl.wrap_socket()is broken and insecure. The function neither sends a SNI TLS extension nor validates the server hostname. Code is subject toCWE 295 (Improper Certificate Validation). (Contributed by Victor Stinner ingh-94199.)

unittest

webbrowser

  • Remove support for obsolete browsers fromwebbrowser. The removed browsers include: Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape, Firebird, and Firefox versions 35 and below (gh-102871).

xml.etree.ElementTree

  • Remove theElementTree.Element.copy()method of the pure Python implementation, deprecated in Python 3.10, use the copy.copy()function instead. The C implementation ofxml.etree.ElementTree has nocopy()method, only a__copy__()method. (Contributed by Victor Stinner ingh-94383.)

zipimport

  • Removezipimport’sfind_loader()andfind_module()methods, deprecated in Python 3.10: use thefind_spec()method instead. See PEP 451for the rationale. (Contributed by Victor Stinner ingh-94379.)

Others

  • Remove thesuspiciousrule from the documentationMakefileand Doc/tools/rstlint.py,both in favor ofsphinx-lint. (Contributed by Julien Palard ingh-98179.)

  • Remove thekeyfileandcertfileparameters from the ftplib,imaplib,poplibandsmtplibmodules, and thekey_file,cert_fileandcheck_hostnameparameters from the http.clientmodule, all deprecated since Python 3.6. Use thecontextparameter (ssl_contextinimaplib) instead. (Contributed by Victor Stinner ingh-94172.)

  • RemoveJythoncompatibility hacks from several stdlib modules and tests. (Contributed by Nikita Sobolev ingh-99482.)

  • Remove_use_broken_old_ctypes_structure_semantics_flag fromctypesmodule. (Contributed by Nikita Sobolev ingh-99285.)

Porting to Python 3.12

This section lists previously described changes and other bugfixes that may require changes to your code.

Changes in the Python API

  • More strict rules are now applied for numerical group references and group names in regular expressions. Only sequence of ASCII digits is now accepted as a numerical reference. The group name in bytes patterns and replacement strings can now only contain ASCII letters and digits and underscore. (Contributed by Serhiy Storchaka ingh-91760.)

  • Removerandrange()functionality deprecated since Python 3.10. Formerly, randrange(10.0)losslessly converted torandrange(10).Now, it raises a TypeError.Also, the exception raised for non-integer values such as randrange(10.5)orrandrange('10')has been changed fromValueErrorto TypeError.This also prevents bugs whererandrange(1e25)would silently select from a larger range thanrandrange(10**25). (Originally suggested by Serhiy Storchakagh-86388.)

  • argparse.ArgumentParserchanged encoding and error handler for reading arguments from file (e.g.fromfile_prefix_charsoption) from default text encoding (e.g.locale.getpreferredencoding(False)) tofilesystem encoding and error handler. Argument files should be encoded in UTF-8 instead of ANSI Codepage on Windows.

  • Remove theasyncore-basedsmtpdmodule deprecated in Python 3.4.7 and 3.5.4. A recommended replacement is the asyncio-basedaiosmtpdPyPI module.

  • shlex.split():PassingNoneforsargument now raises an exception, rather than readingsys.stdin.The feature was deprecated in Python 3.9. (Contributed by Victor Stinner ingh-94352.)

  • Theosmodule no longer accepts bytes-like paths, like bytearrayandmemoryviewtypes: only the exact bytestype is accepted for bytes strings. (Contributed by Victor Stinner ingh-98393.)

  • syslog.openlog()andsyslog.closelog()now fail if used in subinterpreters. syslog.syslog()may still be used in subinterpreters, but now only ifsyslog.openlog()has already been called in the main interpreter. These new restrictions do not apply to the main interpreter, so only a very small set of users might be affected. This change helps with interpreter isolation. Furthermore,syslogis a wrapper around process-global resources, which are best managed from the main interpreter. (Contributed by Donghee Na ingh-99127.)

  • The undocumented locking behavior ofcached_property() is removed, because it locked across all instances of the class, leading to high lock contention. This means that a cached property getter function could now run more than once for a single instance, if two threads race. For most simple cached properties (e.g. those that are idempotent and simply calculate a value based on other attributes of the instance) this will be fine. If synchronization is needed, implement locking within the cached property getter function or around multi-threaded access points.

  • sys._current_exceptions()now returns a mapping from thread-id to an exception instance, rather than to a(typ,exc,tb)tuple. (Contributed by Irit Katriel ingh-103176.)

  • When extracting tar files usingtarfileor shutil.unpack_archive(),pass thefilterargument to limit features that may be surprising or dangerous. SeeExtraction filtersfor details.

  • The output of thetokenize.tokenize()andtokenize.generate_tokens() functions is now changed due to the changes introduced inPEP 701.This means thatSTRINGtokens are not emitted any more for f-strings and the tokens described inPEP 701are now produced instead:FSTRING_START, FSTRING_MIDDLEandFSTRING_ENDare now emitted for f-string “string” parts in addition to the appropriate tokens for the tokenization in the expression components. For example for the f-stringf "start{1+1}end " the old version of the tokenizer emitted:

    1,0-1,18:STRING'f "start {1+1} end" '

    while the new version emits:

    1,0-1,2:FSTRING_START'f "'
1,2-1,8:FSTRING_MIDDLE'start '
1,8-1,9:OP'{'
1,9-1,10:NUMBER'1'
1,10-1,11:OP'+'
1,11-1,12:NUMBER'1'
1,12-1,13:OP'}'
1,13-1,17:FSTRING_MIDDLE' end'
1,17-1,18:FSTRING_END' "'

    Additionally, there may be some minor behavioral changes as a consequence of the changes required to supportPEP 701.Some of these changes include:

    • Thetypeattribute of the tokens emitted when tokenizing some invalid Python characters such as!has changed fromERRORTOKENtoOP.

    • Incomplete single-line strings now also raisetokenize.TokenErroras incomplete multiline strings do.

    • Some incomplete or invalid Python code now raisestokenize.TokenErrorinstead of returning arbitraryERRORTOKENtokens when tokenizing it.

    • Mi xing tabs and spaces as indentation in the same file is not supported anymore and will raise aTabError.

  • Thethreadingmodule now expects the_threadmodule to have an_is_main_interpreterattribute. It is a function with no arguments that returnsTrueif the current interpreter is the main interpreter.

    Any library or application that provides a custom_threadmodule should provide_is_main_interpreter(). (Seegh-112826.)

Build Changes

  • Python no longer usessetup.pyto build shared C extension modules. Build parameters like headers and libraries are detected inconfigure script. Extensions are built byMakefile.Most extensions use pkg-configand fall back to manual detection. (Contributed by Christian Heimes ingh-93939.)

  • va_start()with two parameters, likeva_start(args,format), is now required to build Python. va_start()is no longer called with a single parameter. (Contributed by Kumar Aditya ingh-93207.)

  • CPython now uses the ThinLTO option as the default link time optimization policy if the Clang compiler accepts the flag. (Contributed by Donghee Na ingh-89536.)

  • AddCOMPILEALL_OPTSvariable inMakefileto overridecompileall options (default:-j0) inmakeinstall.Also merged the 3 compileallcommands into a single command to build.pyc files for all optimization levels (0, 1, 2) at once. (Contributed by Victor Stinner ingh-99289.)

  • Add platform triplets for 64-bit LoongArch:

    • loongarch64-linux-gnusf

    • loongarch64-linux-gnuf32

    • loongarch64-linux-gnu

    (Contributed by Zhang Na ingh-90656.)

  • PYTHON_FOR_REGENnow require Python 3.10 or newer.

  • Autoconf 2.71 and aclocal 1.16.4 is now required to regenerate !configure. (Contributed by Christian Heimes ingh-89886.)

  • Windows builds and macOS installers from Python.org now use OpenSSL 3.0.

C API Changes

New Features

  • PEP 683:IntroduceImmortal Objects,which allows objects to bypass reference counts, and related changes to the C-API:

    • _Py_IMMORTAL_REFCNT:The reference count that defines an object

      as immortal.

    • _Py_IsImmortalChecks if an object has the immortal reference count.

    • PyObject_HEAD_INITThis will now initialize reference count to

      _Py_IMMORTAL_REFCNTwhen used withPy_BUILD_CORE.

    • SSTATE_INTERNED_IMMORTALAn identifier for interned unicode objects

      that are immortal.

    • SSTATE_INTERNED_IMMORTAL_STATICAn identifier for interned unicode

      objects that are immortal and static

    • sys.getunicodeinternedsizeThis returns the total number of unicode

      objects that have been interned. This is now needed forrefleak.pyto correctly track reference counts and allocated blocks

    (Contributed by Eddie Elizondo ingh-84436.)

  • PEP 684:Add the newPy_NewInterpreterFromConfig() function andPyInterpreterConfig,which may be used to create sub-interpreters with their own GILs. (SeePEP 684: A Per-Interpreter GILfor more info.) (Contributed by Eric Snow ingh-104110.)

  • In the limited C API version 3.12,Py_INCREF()and Py_DECREF()functions are now implemented as opaque function calls to hide implementation details. (Contributed by Victor Stinner ingh-105387.)

Porting to Python 3.12

  • Legacy Unicode APIs based onPy_UNICODE*representation has been removed. Please migrate to APIs based on UTF-8 orwchar_t*.

  • Argument parsing functions likePyArg_ParseTuple()doesn’t support Py_UNICODE*based format (e.g.u,Z) anymore. Please migrate to other formats for Unicode likes,z,es,andU.

  • tp_weaklistfor all static builtin types is alwaysNULL. This is an internal-only field onPyTypeObject but we’re pointing out the change in case someone happens to be accessing the field directly anyway. To avoid breakage, consider using the existing public C-API instead, or, if necessary, the (internal-only)_PyObject_GET_WEAKREFS_LISTPTR()macro.

  • This internal-onlyPyTypeObject.tp_subclassesmay now not be a valid object pointer. Its type was changed tovoid*to reflect this. We mention this in case someone happens to be accessing the internal-only field directly.

    To get a list of subclasses, call the Python method __subclasses__()(usingPyObject_CallMethod(), for example).

  • Add support of more formatting options (left aligning, octals, uppercase hexadecimals,intmax_t,ptrdiff_t,wchar_tC strings, variable width and precision) inPyUnicode_FromFormat()and PyUnicode_FromFormatV(). (Contributed by Serhiy Storchaka ingh-98836.)

  • An unrecognized format character inPyUnicode_FromFormat()and PyUnicode_FromFormatV()now sets aSystemError. In previous versions it caused all the rest of the format string to be copied as-is to the result string, and any extra arguments discarded. (Contributed by Serhiy Storchaka ingh-95781.)

  • Fix wrong sign placement inPyUnicode_FromFormat()and PyUnicode_FromFormatV(). (Contributed by Philip Georgi ingh-95504.)

  • Extension classes wanting to add a__dict__or weak reference slot should usePy_TPFLAGS_MANAGED_DICTand Py_TPFLAGS_MANAGED_WEAKREFinstead oftp_dictoffsetand tp_weaklistoffset,respectively. The use oftp_dictoffsetandtp_weaklistoffsetis still supported, but does not fully support multiple inheritance (gh-95589), and performance may be worse. Classes declaringPy_TPFLAGS_MANAGED_DICTmust call _PyObject_VisitManagedDict()and_PyObject_ClearManagedDict() to traverse and clear their instance’s dictionaries. To clear weakrefs, callPyObject_ClearWeakRefs(),as before.

  • ThePyUnicode_FSDecoder()function no longer accepts bytes-like paths, likebytearrayandmemoryviewtypes: only the exact bytestype is accepted for bytes strings. (Contributed by Victor Stinner ingh-98393.)

  • ThePy_CLEAR,Py_SETREFandPy_XSETREF macros now only evaluate their arguments once. If an argument has side effects, these side effects are no longer duplicated. (Contributed by Victor Stinner ingh-98724.)

  • The interpreter’s error indicator is now always normalized. This means thatPyErr_SetObject(),PyErr_SetString()and the other functions that set the error indicator now normalize the exception before storing it. (Contributed by Mark Shannon ingh-101578.)

  • _Py_RefTotalis no longer authoritative and only kept around for ABI compatibility. Note that it is an internal global and only available on debug builds. If you happen to be using it then you’ll need to start using_Py_GetGlobalRefTotal().

  • The following functions now select an appropriate metaclass for the newly created type:

    Creating classes whose metaclass overridestp_new is deprecated, and in Python 3.14+ it will be disallowed. Note that these functions ignoretp_newof the metaclass, possibly allowing incomplete initialization.

    Note thatPyType_FromMetaclass()(added in Python 3.12) already disallows creating classes whose metaclass overridestp_new (__new__()in Python).

    Sincetp_newoverrides almost everythingPyType_From*functions do, the two are incompatible with each other. The existing behavior – ignoring the metaclass for several steps of type creation – is unsafe in general, since (meta)classes assume that tp_newwas called. There is no simple general workaround. One of the following may work for you:

    • If you control the metaclass, avoid usingtp_newin it:

      • If initialization can be skipped, it can be done in tp_initinstead.

      • If the metaclass doesn’t need to be instantiated from Python, set itstp_newtoNULLusing thePy_TPFLAGS_DISALLOW_INSTANTIATIONflag. This makes it acceptable forPyType_From*functions.

    • AvoidPyType_From*functions: if you don’t need C-specific features (slots or setting the instance size), create types bycalling the metaclass.

    • If youknowthetp_newcan be skipped safely, filter the deprecation warning out usingwarnings.catch_warnings()from Python.

  • PyOS_InputHookandPyOS_ReadlineFunctionPointerare no longer called insubinterpreters.This is because clients generally rely on process-wide global state (since these callbacks have no way of recovering extension module state).

    This also avoids situations where extensions may find themselves running in a subinterpreter that they don’t support (or haven’t yet been loaded in). See gh-104668for more info.

  • PyLongObjecthas had its internals changed for better performance. Although the internals ofPyLongObjectare private, they are used by some extension modules. The internal fields should no longer be accessed directly, instead the API functions beginningPyLong_...should be used instead. Two newunstableAPI functions are provided for efficient access to the value ofPyLongObjects which fit into a single machine word:

  • Custom allocators, set viaPyMem_SetAllocator(),are now required to be thread-safe, regardless of memory domain. Allocators that don’t have their own state, including “hooks”, are not affected. If your custom allocator is not already thread-safe and you need guidance then please create a new GitHub issue and CC@ericsnowcurrently.

Deprecated

Pending Removal in Python 3.14

Pending Removal in Python 3.15

Pending Removal in Future Versions

The following APIs are deprecated and will be removed, although there is currently no date scheduled for their removal.

Removed

  • Remove thetoken.hheader file. There was never any public tokenizer C API. Thetoken.hheader file was only designed to be used by Python internals. (Contributed by Victor Stinner ingh-92651.)

  • Legacy Unicode APIs have been removed. SeePEP 623for detail.

    • PyUnicode_WCHAR_KIND

    • PyUnicode_AS_UNICODE()

    • PyUnicode_AsUnicode()

    • PyUnicode_AsUnicodeAndSize()

    • PyUnicode_AS_DATA()

    • PyUnicode_FromUnicode()

    • PyUnicode_GET_SIZE()

    • PyUnicode_GetSize()

    • PyUnicode_GET_DATA_SIZE()

  • Remove thePyUnicode_InternImmortal()function macro. (Contributed by Victor Stinner ingh-85858.)